Dev GuideAPI Reference
Dev GuideAPI Reference
Dev GuideAPI ReferenceDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
Dev CommunityOptimizely AcademySubmit a ticket
Start typing to search…
  1. Deploy DXP

Troubleshoot smooth deployment

Fix smooth deployment failures in Optimizely DXP. Diagnose common errors, resolve configuration conflicts, and restore stable deployments fast.

Start a deployment

When you are ready to recover, start a deployment. The deployment system will automatically detect the existing maintenance mode and resume the smooth deployment process.

Choose your package

  • Same package – If the failure was environmental (timeout, transient issue) and you fixed the environment.
  • Different package – If the failure was code-related (startup errors, ReadOnly mode not supported) and you fixed the code.

Choose your deployment mode

  • Smooth Deploy – If you fixed the underlying issue.

What happens during recovery:

  1. System detects your environment is in maintenance mode.
  2. System resumes the smooth deployment process.
  3. Deployment proceeds normally.

Your environment can remain in maintenance mode in two scenarios during Smooth Deploy (Zero Downtime Deployment):

Failed deployment status

Your deployment entered maintenance mode but failed during the deployment process when any of the following occurs:

  • Deployment status displays Failed in DXP Portal.
  • Deployment logs contain All sites in this deployment are now in maintenance mode, followed by errors.
  • Complete and Reset are unavailable.

Partial failure in multi-webapp projects

If your project has multiple web apps (for example, Optimizely Content Management System (CMS) + Optimizely Commerce Connect, or a project with a scheduler/manager webapp), some web apps can enter maintenance mode while others fail. In this case, the deployment logs show:

At least one maintenance mode operation failed. Investigate the logs and try again.

The All sites in this deployment are now in maintenance mode message will not display. However, the web apps that succeeded are stuck in maintenance mode — the system does not clean them up.

How to tell which web apps were affected

Look for per-site log messages that display before the failure:

  • Enabling zero downtime deployment mode <mode> on site <name> – the main webapp attempted a ZDD slot swap.
  • Putting site <name> in maintenance mode – a non-ZDD webapp (scheduler, manager, failover) attempted a maintenance page swap.

These messages indicate the swap was attempted for that site, but do not confirm it succeeded.

Identify the issue

Investigate the deployment logs and the application logs to understand why the failure occurred. When you identify and resolve the issue, start a deployment, the deployment system automatically detects web apps already in maintenance mode and handles them on retry. If you cannot identify the cause or if retries continue to fail, contact Optimizely Support.

If your deployment failed, troubleshoot the issue before starting a deployment.

Check deployment logs

  1. Go to DXP Portal > your environment > Deployments tab.
  2. Click on the failed deployment.
  3. Review the deployment logs for error messages.
  4. Click Get detailed log to download full logs.

Check application logs

  1. Go to DXP Portal > your project > Troubleshoot tab > Application Logs section.
  2. Download your application logs.
  3. Look for errors during startup, warmup, or validation.

Awaiting verification deployment status

The first part of your deployment succeeded, but you have not clicked Complete or Reset. You can identify awaiting deployment by the following:

  • Deployment status displays Awaiting Verification in DXP Portal.
  • Complete and Reset are available.
  • The site runs in maintenance mode (ReadOnly or ReadWrite). In ReadWrite mode, editors can work, but you might lose changes during the deployment because the system saves data to temporary databases.

When your environment is in maintenance mode during Smooth Deploy, it runs on temporary databases. The system copied production databases to temporary databases. Your site is now using these copies instead of the real databases. The real databases still contain the data from before the deployment started.

Maintenance mode behavior

  • ReadOnly – Users can access the site in read-only mode (no purchases, forms, or edits)
  • ReadWrite – Site appears normal, but editors' changes are saved to the temporary databases
    ❗️

    Warning

    When you start a deployment, the deployment system resumes the smooth deployment process.

    Data loss risk in ReadWrite mode – If editors made changes during the deployment, those changes exist only in the temporary databases.

Troubleshoot deployment issues

ReadOnly database mode not supported

Your application does not support ReadOnly database mode. When Smooth Deploy uses ReadOnly mode, the temporary database is set to read-only. If your application attempts to write to the database during startup or warmup, it fails.

Symptoms

  • "Database is in read-only mode" or "Cannot write to database" errors occur.
  • 503 errors occur during warmup.
  • SqlException referencing the read-only database appears in application logs.

Resolution

  • Implement ReadOnly database mode support in your application. See Database Mode Documentation.
  • If your application cannot support ReadOnly mode, use maintenance page deployment instead.

Warmup failure

The deployment slot must respond with HTTP 200 OK during warmup. This fails when the application takes too long to start or is in a broken state due to crashes, configuration errors, or unhandled exceptions. See also Application startup errors.

Symptom

  • "Site warmup failed" or "Health check timeout" errors occur, the deployment stalls at the warmup phase, and the application returns non-200 HTTP responses during warmup.

Resolution

  • Check application logs for errors during startup.
  • Ensure the application responds with 200 OK on the root path.
  • Optimize application startup time by removing blocking operations such as external API calls and heavy initialization.
  • See Warmup and health check requirements.

Application startup errors

Code errors are preventing the application from starting.

Symptom

  • Stack traces, null reference exceptions, or configuration errors appear in logs, and 500 errors occur during warmup.

Resolution

  • Fix the code issue in your application.
  • Test locally before deploying.
  • Deploy the updated package.

Application-level IP filtering

Requests from Azure infrastructure IPs are blocked by IP filtering middleware or logic in your application code.

Symptom – A "403 (IP Forbidden)" error occurs during slot verification or warmup.

Resolution

  • Review your application for IP filtering middleware or custom request validation.
  • Ensure your application code does not block warmup requests from Azure infrastructure.
  • If you use IP filtering, allow requests on deployment slots or during startup.

Database migration failures

EF migrations or custom database scripts failed.

Symptom

  • SQL errors or migration timeout errors occur during deployment.

Resolution

  • Check migration scripts for errors.
  • Test migrations locally before deploying.
  • Deploy the updated package with fixed migrations.

Deployment credential issues

Kudu deployment credential fetch failed.

Symptom

  • "Failed to build MSDeploy credentials from publish profile" or "Operation returned an invalid status code 'NotFound'" errors occur.

Resolution

  • Retry the deployment — this is usually a transient issue.
  • If the issue persists, contact Optimizely Support.

Frequently asked questions

Why can I not Complete or Reset the failed deployment?

When a deployment fails, the environment did not reach the verification stage where Complete or Reset are possible. The deployment was interrupted before reaching a state where those actions apply. Start a deployment instead — the system will automatically detect the maintenance mode and resume the deployment.

What if your deployment is Awaiting Verification?

If your deployment status is Awaiting Verification, you can either Complete the deployment (to go live with the new code) or Reset the deployment (to roll back). If you don't take action, your environment will continue running in maintenance mode on temporary databases.

Is it safe to start a deployment while in maintenance mode?

Yes. The deployment system is designed to detect maintenance mode and handle it safely. It resumes the smooth deployment process.

Will editors lose work?

Only if you used ReadWrite mode and editors made changes during the deployment. If you cannot accept data loss, you need to use ReadOnly mode or a maintenance page. See Smooth deployment for details about data loss risks.

What if I don't know why the deployment failed?

Check the deployment logs and application logs, and review the common issues section. If you still cannot identify the issue or don't understand the error, contact Optimizely Support.

When to contact Optimizely Support

Contact Optimizely Support if:

  • You cannot identify the issue – You checked deployment logs and application logs but do not understand the error.
  • Deployment continues failing – You identified and fixed the issue, but new deployments still fail.
  • You need immediate recovery – Your environment must be brought to normal state as soon as possible.
📘

Note

If deployments continue failing repeatedly, you may have to get help from Optimizely Support. However, if the issue is in your application code, you should identify and fix it first before contacting Optimizely Support.

What to include in your support ticket

  • Project ID
  • Environment name
  • Deployment ID
  • Relevant log messages you identified during the investigation
  • Description of the error and what you've tried

Updated about 4 hours ago