Skip to content
Optimizely CertificationOptimizely Certification Optimizely Certification

Troubleshoot Deployments

⏱ 20 minutes intermediate
📜Corecms

Why deployments fail

Section titled “Why deployments fail”

Deployments fail for predictable reasons. A missing package, a configuration error, an unhandled exception on startup. The key to fast resolution is knowing where to look. This guide walks through the most common failure scenarios and their fixes.

Step 1: Check the deployment log

Section titled “Step 1: Check the deployment log”

Every deployment produces a detailed log. Start here.

  1. In the management portal, navigate to Deployments
  2. Find the failed deployment (marked with a red status)
  3. Click to expand the log
  4. Scroll to the first error message — this is usually the root cause

Interpreting error logs

Section titled “Interpreting error logs”

Deployment logs often contain dozens of error lines, but most are cascading failures caused by a single root issue. Follow this approach to find the actual cause:

  • Read from the top down. The first error in the log is almost always the root cause. Everything after it is typically a consequence (failed dependency injection, downstream services timing out, etc.).
  • Look for these common root-cause patterns first:
    • FileNotFoundException or Could not load file or assembly — A missing DLL or version mismatch. Check NuGet packages and binding redirects.
    • InvalidOperationException: Unable to resolve service — A dependency injection registration is missing. Look for the type name in the error to identify which service was not registered.
    • SqlException or Login failed — Database connectivity. Check connection strings and environment variable configuration.
    • error CS followed by a number — A compilation error. The code does not build. Fix the build error locally first.
  • Ignore lines that say “The application shut down” or “Health check failed” at the end of the log — these are consequences of the earlier failure, not the cause.
  • Search for the word “Unhandled” — Unhandled exceptions during startup are almost always the root issue.
  • If the log is truncated, re-run the deployment with verbose logging enabled (if available) or check Application Insights for the startup exception.

Build failures

Section titled “Build failures”

NuGet restore errors

Section titled “NuGet restore errors”

Symptom: Log shows “Unable to find package” or “package source not found”

Fixes:

  • Verify nuget.config in your repository root includes all required feeds
  • Ensure the Optimizely NuGet feed URL is correct: https://nuget.optimizely.com/feed/packages.svc/
  • Check that private feed credentials are configured in the portal

Compilation errors

Section titled “Compilation errors”

Symptom: Log shows CS errors (e.g., error CS1061: 'Type' does not contain a definition for 'Method')

Fixes:

  • Build locally with dotnet build --configuration Release to reproduce
  • Check for .NET SDK version mismatches between your local environment and the cloud build
  • Verify all project references resolve correctly

Build timeout

Section titled “Build timeout”

Symptom: Log shows “Build exceeded maximum duration”

Fixes:

  • Optimize build by removing unnecessary projects from the solution
  • Pre-compile client-side assets locally and commit the output
  • Contact support to increase the build timeout if your solution is genuinely large

Startup failures

Section titled “Startup failures”

The build succeeded but the application crashes on startup.

Missing environment variables

Section titled “Missing environment variables”

Symptom: Log shows InvalidOperationException: Connection string 'EPiServerDB' not found or similar configuration errors

Fixes:

  • Check that all required environment variables are set for the target environment
  • Verify variable names match exactly (case-sensitive)
  • Use the management portal to review configured variables

Database migration errors

Section titled “Database migration errors”

Symptom: Log shows SQL errors during startup or “database schema is not up to date”

Fixes:

  • Verify the database is accessible from the target environment
  • Run pending migrations manually if the automatic migration failed
  • Check for conflicting schema changes between environments

Assembly loading errors

Section titled “Assembly loading errors”

Symptom: Log shows FileNotFoundException or FileLoadException for a specific DLL

Fixes:

  • Verify the assembly is included in your deployment package
  • Check for version conflicts between NuGet packages
  • Ensure binding redirects are correct in web.config or assembly resolution is handled in code

Health check failures

Section titled “Health check failures”

The application started but the platform’s health checks are failing.

HTTP health check returns non-200

Section titled “HTTP health check returns non-200”

Symptom: Deployment log shows “Health check failed” followed by automatic rollback

Fixes:

  • Test the health check endpoint locally: curl http://localhost:5000/health
  • Check that the health check path matches what the platform expects (typically the root URL or /health)
  • Verify the application responds within the timeout window (default: 30 seconds)
  • Look for exceptions in the application log during the health check period

Warmup timeout

Section titled “Warmup timeout”

Symptom: The application takes too long to respond to the first request after deployment

Fixes:

  • Optimize application startup by deferring non-critical initialization
  • Pre-compile views if using Razor pages
  • Reduce the number of startup tasks that run synchronously

Post-deployment issues

Section titled “Post-deployment issues”

The deployment succeeded but something is wrong on the live site.

500 errors on specific pages

Section titled “500 errors on specific pages”

Symptom: Most pages work but certain pages return server errors

Fixes:

  • Check Application Insights for the specific exception
  • Look for content type changes that affect existing content
  • Verify any new dependencies (search indexes, external APIs) are available in the target environment

Performance degradation

Section titled “Performance degradation”

Symptom: Site is slower after deployment

Fixes:

  • Compare Application Insights metrics before and after deployment
  • Check for new N+1 query patterns in the deployment’s code changes
  • Verify CDN cache is warming up (first requests after deployment are slower)
  • Look for synchronous external API calls that should be async

Static assets returning 404

Section titled “Static assets returning 404”

Symptom: CSS, JavaScript, or images are not loading

Fixes:

  • Verify UseStaticFiles() is called in the middleware pipeline
  • Check that the build step includes your frontend assets in the output
  • If using bundled/hashed filenames, ensure the manifest file is included in the deployment

Rollback a deployment

Section titled “Rollback a deployment”

If a deployment causes issues that cannot be fixed quickly:

Automatic rollback

Section titled “Automatic rollback”

If health checks fail during deployment, the platform rolls back automatically. No action is needed.

Manual rollback

Section titled “Manual rollback”
  1. In the management portal, navigate to Deployments
  2. Find the last successful deployment
  3. Click Redeploy
  4. Wait for the rollback deployment to complete
  5. Verify the site is functioning correctly

Remember: Rollback reverts code but not database changes. If the failed deployment included schema migrations, you may need to address the database separately.

Handling backward-incompatible database migrations during rollback

Section titled “Handling backward-incompatible database migrations during rollback”

Rolling back code while the database schema has moved forward is the most common cause of post-rollback failures. Follow these guidelines:

  • Prefer additive migrations. Add new columns as nullable, add new tables, but do not rename or drop columns in the same deployment that introduces the code using them. This keeps the schema backward-compatible so rolling back the code does not break against the updated database.
  • If you deployed a destructive migration (dropped a column, renamed a table, changed a data type), rolling back the code alone will cause runtime errors because the code expects the old schema. In this case:
    1. Write a compensating migration that restores the old schema elements (re-add the dropped column, create a view with the old name, etc.)
    2. Deploy the compensating migration as a hotfix before redeploying the previous code version
    3. Verify the application starts and passes health checks against the restored schema
  • If you deployed a data migration (backfilled values, moved rows between tables), assess whether the data change is reversible. If not, the rollback plan should address the data state explicitly — document this in your deployment plan before deploying.
  • Test rollback in a non-production environment whenever your deployment includes schema changes. Deploy the migration to Integration, then redeploy the previous code version and verify the application functions correctly.

Prevention checklist

Section titled “Prevention checklist”

Before deploying, verify:

  • Application builds successfully in Release configuration locally
  • All tests pass
  • Environment variables are configured for the target environment
  • Database migrations are backward-compatible
  • Health check endpoint responds correctly
  • No hardcoded environment-specific values in code
Section titled “Related resources”