Troubleshoot smooth deployment
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:
- System detects your environment is in maintenance mode.
- System resumes the smooth deployment process.
- 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, a scheduler or failover web app), 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 or 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
- Go to DXP Portal > your environment > Deployments tab.
- Click on the failed deployment.
- Review the deployment logs for error messages.
- Click Get detailed log to download full logs.
Check application logs
- Go to DXP Portal > your project > Troubleshoot tab > Application Logs section.
- Download your application logs.
- 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.
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 deploymentSmooth 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