Deployment Failures¶

1. Summary¶

This playbook applies when deployment to Azure App Service finishes with an error, appears successful but does not activate correctly, or fails during slot swap and promotion. Use it for ZipDeploy, GitHub Actions, Azure DevOps, local ZIP pushes, container image updates, and deployment slot swap workflows.

Symptoms¶

• Deployment Center or CI/CD shows Deployment failed, Package deployment using ZIP Deploy failed, or Oryx build failed.
• A slot swap reports warm-up timeout, validation failure, or rollback.
• New content exists in the staging slot, but production still serves the old version.
• Deployment history shows success while the app returns 503, 500, or health check failures immediately after release.

Common error messages¶

• Failed to deploy web package to App Service.
• Package deployment failed. Extract zip failed.
• The deployment request failed because the app is restarting.
• Slot swap operation has failed because the source slot could not be warmed up.
• Container didn't respond to HTTP pings on port.

flowchart TD
    A[Deployment failure reported] --> B{Did artifact reach App Service?}
    B -->|No| H1[H1: CI/CD or deployment transport failure]
    B -->|Yes| C{Did build or extraction fail?}
    C -->|Yes| H2[H2: Package or build failure]
    C -->|No| D{Did app start after deployment?}
    D -->|No| H3[H3: Startup/runtime issue after successful deploy]
    D -->|Yes| E{Was slot swap involved?}
    E -->|Yes| H4[H4: Warm-up or slot configuration drift]
    E -->|No| F[Check deployment history and artifact activation]

Release phase timeline¶

A successful CI pipeline proves only that the pipeline finished. Between the artifact and the first healthy business request the release crosses several boundaries, and extraction and package mounting are alternative branches rather than consecutive steps.

%% diagram-id: deployment-release-phase-timeline
flowchart TD
    A[CI build or source packaging] --> B[Artifact identity<br/>hash and package layout]
    B --> C[SCM authorization and upload<br/>a remote package URL is read by the runtime instead]
    C --> D{Deployment mode}
    D -->|Ordinary ZIP deploy| E[Extraction into wwwroot<br/>optional build automation]
    D -->|Run From Package| F[Already-runnable ZIP<br/>mounted as read-only wwwroot]
    E --> G[Restart and startup]
    F --> G
    G --> H[Warm-up]
    H --> I[Health check]
    I --> J[Representative business request]

Do not assume an exact ordering inside Kudu beyond what the deployment logs show. For how the mounted package works, see Run From Package.

2. Common Misreadings¶

3. Competing Hypotheses¶

4. What to Check First¶

1. Inspect deployment history and the latest deployment record

   az webapp log deployment list \
       --resource-group $RG \
       --name $APP_NAME \
       --output table
   

   Command	Purpose
   az webapp log deployment list --resource-group $RG --name $APP_NAME --output table	Lists deployment history records so you can verify whether the latest deployment completed.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --output table	Formats the command output as a readable table for quick triage.

2. Check app state, host name, and current slot swap status

   az webapp show \
       --resource-group $RG \
       --name $APP_NAME \
       --query "{state:state,defaultHostName:defaultHostName,slotSwapStatus:slotSwapStatus}" \
       --output json
   

   Command	Purpose
   az webapp show --resource-group $RG --name $APP_NAME --query "{state:state,defaultHostName:defaultHostName,slotSwapStatus:slotSwapStatus}" --output json	Shows the app state, default hostname, and slot-swap status so you can confirm whether deployment reached the expected activation phase.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "{state:state,defaultHostName:defaultHostName,slotSwapStatus:slotSwapStatus}"	Projects only these named top-level properties into a smaller object before formatting the output.
   --output json	Formats the command output as JSON for full-fidelity inspection.

3. If slots are involved, list slot inventory and state

   az webapp deployment slot list \
       --resource-group $RG \
       --name $APP_NAME \
       --query "[].{name:name,state:state,host:defaultHostName}" \
       --output table
   

   Command	Purpose
   az webapp deployment slot list --resource-group $RG --name $APP_NAME --query "[].{name:name,state:state,host:defaultHostName}" --output table	Lists deployment slots so you can compare slot names, state, and hostnames.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "[].{name:name,state:state,host:defaultHostName}"	Projects each returned array element into the listed fields before formatting the output.
   --output table	Formats the command output as a readable table for quick triage.

4. Inspect runtime configuration that affects activation after deployment

   az webapp config show \
       --resource-group $RG \
       --name $APP_NAME \
       --query "{linuxFxVersion:linuxFxVersion,appCommandLine:appCommandLine,alwaysOn:alwaysOn}" \
       --output json
   

   Command	Purpose
   az webapp config show --resource-group $RG --name $APP_NAME --query "{linuxFxVersion:linuxFxVersion,appCommandLine:appCommandLine,alwaysOn:alwaysOn}" --output json	Shows the effective site configuration so you can inspect the runtime or startup-related properties.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "{linuxFxVersion:linuxFxVersion,appCommandLine:appCommandLine,alwaysOn:alwaysOn}"	Projects only these named top-level properties into a smaller object before formatting the output.
   --output json	Formats the command output as JSON for full-fidelity inspection.

5. Review deployment-critical app settings

   az webapp config appsettings list \
       --resource-group $RG \
       --name $APP_NAME \
       --query "[?name=='SCM_DO_BUILD_DURING_DEPLOYMENT' || name=='WEBSITE_RUN_FROM_PACKAGE' || name=='WEBSITES_PORT' || name=='WEBSITE_SWAP_WARMUP_PING_PATH'].{name:name,value:value}" \
       --output table
   

   Command	Purpose
   az webapp config appsettings list --resource-group $RG --name $APP_NAME --query "[?name=='SCM_DO_BUILD_DURING_DEPLOYMENT' \|\| name=='WEBSITE_RUN_FROM_PACKAGE' \|\| name=='WEBSITES_PORT' \|\| name=='WEBSITE_SWAP_WARMUP_PING_PATH'].{name:name,value:value}" --output table	Lists app settings so you can verify the effective configuration keys involved in this scenario.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "[?name=='SCM_DO_BUILD_DURING_DEPLOYMENT' \|\| name=='WEBSITE_RUN_FROM_PACKAGE' \|\| name=='WEBSITES_PORT' \|\| name=='WEBSITE_SWAP_WARMUP_PING_PATH'].{name:name,value:value}"	Filters the returned list with JMESPath, then projects only the named fields into a smaller object per item.
   --output table	Formats the command output as a readable table for quick triage.

Activity log is the control-plane source of truth for when a deployment, restart, or slot swap happened, which is what this timeline needs. Filter Operation name for values such as Restart Web App, Swap Slots, Update site config, Stop Web App, or Start Web App, and tighten Timespan to the incident window. The Event initiated by column separates user actions from CI service principals, and a Succeeded status proves only that the ARM operation completed, not that the worker is serving traffic. Use Download as CSV to attach the timeline to the ticket.

5. Evidence to Collect¶

Collect one timeline that includes deployment start, deployment end, app restart, first healthy response, and any swap event. That timeline prevents mixing build failures with startup failures.

5.1 KQL Queries¶

Query 1: Deployment-adjacent platform failures¶

AppServicePlatformLogs
| where TimeGenerated > ago(24h)
| where Message has_any ("deployment", "ZipDeploy", "ContainerTimeout", "StoppingSiteContainers", "swap")
| project TimeGenerated, Level, Message
| order by TimeGenerated desc

Query 2: HTTP behavior after release¶

AppServiceHTTPLogs
| where TimeGenerated > ago(24h)
| summarize Requests=count(), Errors=countif(ScStatus >= 500), P95=percentile(TimeTaken, 95) by bin(TimeGenerated, 5m), ScStatus
| order by TimeGenerated asc

Query 3: Startup console evidence after a green deployment¶

AppServiceConsoleLogs
| where TimeGenerated > ago(24h)
| where ResultDescription has_any ("Oryx", "gunicorn", "Listening at", "ModuleNotFoundError", "npm ERR", "dotnet", "java")
| project TimeGenerated, Level, ResultDescription
| order by TimeGenerated desc

5.2 CLI Investigation¶

# Show the latest deployment records
az webapp log deployment list \
    --resource-group $RG \
    --name $APP_NAME \
    --output json

Sample output:

[
  {
    "active": true,
    "author": "GitHubActions",
    "complete": true,
    "deployer": "ZipDeploy",
    "end_time": "2026-04-07T08:11:39Z",
    "id": "00000000-0000-0000-0000-000000000000",
    "message": "Created via push deployment"
  }
]

Interpretation:

• complete: true proves transport finished.
• active: true means this package should be the active content unless startup or routing failed afterward.
• A green deployment record does not disprove H3.

# Inspect slot state and swap status
az webapp show \
    --resource-group $RG \
    --name $APP_NAME \
    --query "{state:state,slotSwapStatus:slotSwapStatus,host:defaultHostName}" \
    --output json

Sample output:

{
  "host": "<azurewebsites-domain-redacted>",
  "slotSwapStatus": {
    "destinationSlotName": "production",
    "sourceSlotName": "staging",
    "timestampUtc": "2026-04-07T08:12:01Z"
  },
  "state": "Running"
}

Interpretation:

• Running control plane state does not guarantee the worker is ready.
• Recent slotSwapStatus confirms the release path included slot promotion.
• Correlate this with HTTP and platform logs before repeating the swap.

5.3 Evidence by release phase¶

App Service does not provide a universal file-operation audit stream. When you need to know who wrote or removed a file, rely only on evidence you instrumented yourself, such as application audit events or a pipeline artifact manifest.

Differentiating the failure class¶

6. Validation and Disproof by Hypothesis¶

H1: Deployment transport or Kudu orchestration failed¶

Proves if deployment history is incomplete, missing, or ends before activation with timeout/auth/upload errors.

Disproves if the latest record is complete and logs move on to startup evidence.

Validation steps:

1. Confirm the latest deployment shows complete: true.
2. Re-check whether SCM restarted or a second deployment interrupted the first one.
3. If using external CI/CD, compare pipeline timestamp with App Service deployment timestamp.
4. To test whether deployments are serialized, use two controlled deployments with unique artifact IDs or hashes. Start deployment A; once A has a deployment ID and is still non-terminal, submit deployment B on purpose. Capture comparable server-side start and end timestamps and the final status of both. Overlapping execution intervals show concurrency; B starting only after A reaches a terminal state shows serialization. A record that never completes is evidence of interruption, not proof of overlap.

H2: Artifact, package shape, or build phase failed¶

Proves if build logs contain the first fatal package, dependency, extraction, or post-build command failure.

Disproves if the artifact is deployed and startup logs show the app process actually launching.

Validation steps:

1. Identify whether SCM_DO_BUILD_DURING_DEPLOYMENT matches the artifact type.
2. Confirm the artifact includes the expected startup files and dependency manifest.
3. If WEBSITE_RUN_FROM_PACKAGE is enabled, verify the package itself contains the runnable app layout. See Run From Package for the documented package requirements and limits.
4. If extraction failed on ordinary ZIP deploy, check whether the running app holds files in wwwroot open. Microsoft Learn notes that deployment and runtime share wwwroot on every method except Run From Package, so lock conflicts are possible there.
5. Treat Run From Package as a mitigation only where the runtime supports it. It is unsupported for Python apps and Java apps on Azure App Service, and an app that writes to wwwroot must move that state elsewhere first.

H3: Deployment succeeded but startup failed¶

Proves if deployment history is green while platform logs show ContainerTimeout, port mismatch, crash loop, or repeated restarts.

Disproves if the app serves healthy traffic immediately after deployment.

Validation steps:

1. Correlate deployment end time with the first startup error.
2. Inspect console logs for entrypoint, port, dependency, or runtime-version mismatches.
3. Follow Deployment Succeeded but Startup Failed if H3 dominates.

H4: Slot swap warm-up or slot config drift¶

Proves if staging is healthy enough for manual browsing but swap still fails during warm-up or rollback.

Disproves if no slots were used or swap was never triggered.

Validation steps:

1. Compare staging and production slot settings that should or should not be sticky.
2. Review warm-up path, accepted statuses, and startup budget.
3. Follow Slot Swap Failed During Warm-up for deeper isolation.

7. Likely Root Cause Patterns¶

Build-mode decision matrix¶

Choose the deployment mode from what the pipeline publishes.

8. Immediate Mitigations¶

1. Freeze repeated deployments until one full evidence set is captured.
2. If production is unhealthy, roll back by swapping back or redeploying the last known good package.
3. If only staging is broken, stop promotion and validate startup in the slot URL before retrying.
4. Correct deployment mode mismatches such as run-from-package vs build-on-deploy, using the build-mode decision matrix in section 7.
5. If warm-up is the blocker, temporarily use a lighter readiness path that proves the worker can accept traffic.
6. Re-run the release only after confirming the first failing phase is fixed.

9. Prevention¶

Prevention checklist¶

• [ ] Standardize one deployment method per app and document whether build happens in CI or in App Service.
• [ ] Keep a lightweight health or readiness path available for swap validation.
• [ ] Validate startup command, runtime stack, and slot-sticky settings before production promotion.
• [ ] Record deployment ID, commit SHA, and release timestamp in the app for quick correlation.
• [ ] Test rollback regularly so teams can recover without improvisation.

See Also¶

• Playbooks
• Deployment Succeeded but Startup Failed
• Slot Swap Failed During Warm-up
• Deployment Slots Operations
• Run From Package
• Lab: ZIP Deploy File Lock, Run From Package, and Deployment Serialization
• ZIP Deploy and Run From Package (operations)
• Deployment Options Reference

Sources¶

• Deploy files to Azure App Service (Microsoft Learn)
• Deploy to deployment slots in Azure App Service (Microsoft Learn)
• Enable diagnostics logging for Azure App Service (Microsoft Learn)
• Run your app from a ZIP package (Microsoft Learn)
• Deployment best practices (Microsoft Learn)