az webapp troubleshoot

Preview

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Diagnose common Linux web app problems.

Preview command group that pairs built-in configuration checks (from KuduLite on the worker) with per-instance runtime status and startup summaries from ARM. Use when a Linux app is failing to start, returning HTTP 502/503, or exhibiting other post-deployment misbehavior.

Commands

Name	Description	Type	Status
az webapp troubleshoot collect	Collect diagnostic artifacts from a Linux web app.	Core	Preview
az webapp troubleshoot collect network-capture	Collect and analyze a packet capture from a Linux web app container.	Core	Preview
az webapp troubleshoot config	Validate configuration for a Linux web app and surface a recent runtime error.	Core	Preview
az webapp troubleshoot deployment	Show the latest deployment state and diagnostic information for a Linux web app.	Core	Preview
az webapp troubleshoot status	Show site runtime status and recent startup summary for a Linux web app.	Core	Preview

az webapp troubleshoot config

Preview

Command group 'webapp troubleshoot' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Validate configuration for a Linux web app and surface a recent runtime error.

Aggregates two data sources into a single report: (1) Built-in configuration checks — a set of common Linux App Service settings (linuxFxVersion, port binding, startup command, alwaysOn, health check path, ...) evaluated against the running site's configuration snapshot. (2) The site runtime status error reported by App Service for the worker represented by the configuration-check snapshot. Use --instance with a worker machine name to retrieve that worker's configuration checks. The instance ID returned by those checks is used to select the matching runtime error. If the configuration snapshot is unavailable, the machine name is resolved through ARM so an error from another worker is not returned. Runtime errors are surfaced only when they occurred within the last 15 minutes. Older errors are omitted from both structured output and the --report view. For a 24-hour lookback of runtime status and startup attempts, run az webapp troubleshoot status. By default the command returns a structured payload so the standard -o json/yaml/tsv/table formatters handle output. Pass --report to print a human-readable two-section report to stdout instead.

az webapp troubleshoot config --name
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--instance]
                              [--report {false, true}]
                              [--slot]

Examples

Run the built-in configuration checks and show a recent runtime error, if any (JSON by default)

az webapp troubleshoot config --name MyWebApp --resource-group MyResourceGroup

Print the human-readable report

az webapp troubleshoot config --name MyWebApp --resource-group MyResourceGroup --report

Target a deployment slot

az webapp troubleshoot config --name MyWebApp --resource-group MyResourceGroup --slot staging

Run checks and show a recent runtime error for a specific worker instance

az webapp troubleshoot config --name MyWebApp --resource-group MyResourceGroup --instance lw0sdlwk000002

Required Parameters

--name -n

Name of the web app. If left unspecified, a name will be randomly generated. You can configure the default using az configure --defaults web=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--instance

Filter configuration checks by worker machine name. The runtime error recommendation uses the corresponding ARM instance ID and never falls back to another worker.

--report

Print a human-readable report instead of the structured payload.

Property	Value
Default value:	False
Accepted values:	false, true

--slot -s

The name of the slot. Defaults to the production slot if not specified.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az webapp troubleshoot deployment

Preview

Command group 'webapp troubleshoot' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show the latest deployment state and diagnostic information for a Linux web app.

Returns a point-in-time snapshot from Kudu and enriches it with platform build and runtime status when available. The command supports Linux web apps and does not wait for deployment completion.

az webapp troubleshoot deployment --name
                                  --resource-group
                                  [--acquire-policy-token]
                                  [--change-reference]
                                  [--slot]

Examples

Show the latest deployment status for a web app.

az webapp troubleshoot deployment --resource-group ResourceGroup --name AppName

Show the latest deployment status for a deployment slot.

az webapp troubleshoot deployment --resource-group ResourceGroup --name AppName --slot staging

Required Parameters

--name -n

Name of the web app. If left unspecified, a name will be randomly generated. You can configure the default using az configure --defaults web=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--slot -s

Name of the web app slot. Defaults to the production slot.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az webapp troubleshoot status

Preview

Command group 'webapp troubleshoot' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show site runtime status and recent startup summary for a Linux web app.

Aggregates two data sources:

Site Runtime Status
Startup summary: KuduLite (SCM) /api/startuplogs/summary (counts of successful and failed startup attempts in the last 24h, plus the most recent success and failure timestamps).

Use --instance to scope both to a single worker. By default the command returns a structured payload so the standard -o json/yaml/table formatters handle output. Pass --report to print a human-readable two-section report to stdout instead.

az webapp troubleshoot status --name
                              --resource-group
                              [--acquire-policy-token]
                              [--change-reference]
                              [--instance]
                              [--report {false, true}]
                              [--slot]

Examples

Show status for all instances of a web app (JSON by default)

az webapp troubleshoot status --name MyWebApp --resource-group MyResourceGroup

Print the human-readable report

az webapp troubleshoot status --name MyWebApp --resource-group MyResourceGroup --report

Show status scoped to a single worker instance

az webapp troubleshoot status --name MyWebApp --resource-group MyResourceGroup --instance 7c2d9

Required Parameters

--name -n

Name of the web app. If left unspecified, a name will be randomly generated. You can configure the default using az configure --defaults web=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--instance

Scope the report to a single worker instance.

Accepts either the hex instanceId (from az webapp list-instances) or the machine name (e.g. lw0sdlwk0007AB). When omitted, returns an overview of every instance seen in the last 24 hours.

--report

Print a human-readable, color-coded report instead of returning structured data.

When set, the command writes a formatted report (overview table plus per-instance Last runtime status and Startup summary) to stdout and returns no machine-readable output. Omit --report to keep the default structured payload that works with -o json, -o yaml, and -o table.

Property	Value
Default value:	False
Accepted values:	false, true

--slot -s

The name of the slot. Defaults to the production slot if not specified.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

Feedback

Was this page helpful?