Troubleshooting

Find out why your app did not build, deploy, or respond as expected.

At a glance

• Start with the app name and failed version or deployment.
• Creating an app or saving settings does not mean deployment succeeded.
• Use build logs for compilation and deployment logs for activation.
• If a response is lost, check the saved settings and deployment status before retrying.

Find the failing stage

In Portal, inspect Versions, Deployments, and Overview. In CLI, use app version build-log, app deployment show, and app deploymentlog with the actual IDs. For ARM operations, keep the returned operation URL and error. Do not copy tokens, sensitive variable values, or secret-bearing logs into public reports.

Symptom	Check / action
ARM authorization denied or subscription missing	Check your Microsoft account, tenant, Azure permissions, and preview access
Versions or Deployments fail to load	Retry the read in the Portal. If the problem persists, contact your Private Preview team with a sanitized description; existing deployments can keep serving
GitHub repository missing or unauthorized	GitHub user account, repository access, integration installation access; reauthorize source
builder.yaml not found	Add the manifest to the selected source root, push it, and deploy the existing app
YAML validation fails	Unknown/duplicate fields, unsupported platform, unsafe paths, duplicate names/mounts
No build behavior matches	Use the manifest for your app type and include its required project files
Static output missing after custom build	Place files beneath $DESTINATION_DIR; resolve output beneath that generated root
Version ready but deployment fails	Read the deployment error; check runtime availability, retained build output, and the app's health response
Node.js builds but activation reports an unsupported compute platform	Confirm target runtime availability; use another confirmed runtime rather than retrying the same unsupported output
CLI stops waiting with HTTP 429 / Too Many Requests	The accepted operation may still be running. Check its existing status and deployment history before submitting another deployment
PHP build succeeds but startup or health fails	Keep default nginx/PHP-FPM startup and check the packaged document root
A second deployment is blocked	Track the pending deployment and respect retry guidance; do not assume the active app failed
Build allowance or concurrency limit reached	Read error.serviceLimit; wait until retryAt or until an active build completes, then retry. Reuse the same request ID only for the same uncertain deployment intent
Build timed out	Inspect the version build log, reduce checkout/build/publication time, and start a new build; the timed-out start remains charged
Saved variables appear unchanged	Desired values require a new version; GET names alone cannot confirm value-only edits
App cannot use managed identity	Confirm the identity deployment succeeded, the destination role is assigned to the identity's principal ID, destination firewall rules allow the app, and AZURE_CLIENT_ID selects the intended user-assigned identity. See managed identity

GitHub access problems

If an organization is missing, expand Organization missing? and select Review GitHub access. Review organization approval for the App Service Builder OAuth App and complete your organization's SSO sign-in if required. Organization membership alone does not grant application access. Return to Builder and select Refresh access.

If a repository is missing, check both your GitHub permissions and the GitHub App installation's repository selection. Use Change account to choose another GitHub account; this does not change your Microsoft Portal account. Reconnect if GitHub has expired or revoked your sign-in.

GitHub rejects source access or a fork

When GitHub provides an error message, Builder includes that reason and GitHub's HTTP status in the error. Fork failures identify whether GitHub rejected the destination check or fork creation. A failed destination check means Builder has not attempted to create the fork on that attempt. Validation failures can also include GitHub's repository-name or existing-fork details.

In the template fork form, check Destination before retrying. Choose the intended account or organization and a valid repository name. You can also open the template's GitHub link and create a fork there, then choose Use my repository and select that fork.

Use the reported reason to decide what to fix. For access restrictions, review the connected GitHub account, repository permissions, OAuth App organization approval, and any required SSO sign-in. GitHub App installation access is separate; see GitHub authorization. For repository-name or existing-fork errors, check the destination on GitHub before retrying. For rate limits, wait before retrying rather than repeatedly reconnecting.

If fork creation returns HTTP 403 with "Resource protected by organization SAML enforcement", GitHub is enforcing organization single sign-on (SSO) for that request. Select Fork on GitHub in the error message and create the fork on GitHub. Return to Builder and choose Use my repository. Select the account or organization containing your fork, then its repository and branch. The original GitHub error remains visible, and Builder does not treat opening GitHub as a successful fork.

Before sharing an error publicly, remove credentials and private organization or repository details.

Builder YAML not found

You may see a message saying the app was created but deployment could not be started, followed by:

Source revision '<commit-sha>' does not contain builder.yaml.

The app resource exists, but the selected GitHub commit is missing the manifest at the app's configured source root. For a new app, successful resource creation does not mean an application is running. Keep the existing app; fix its source before retrying rather than creating another app.

1. In Settings → Source Control, confirm the repository and branch, then open that branch in GitHub.
2. Check for builder.yaml at the app source root. Portal creation uses repository root. A configured root such as apps/store needs apps/store/builder.yaml.
3. Add the manifest for your app type using the guide or a sample. Do not use a static-site manifest for an HTTP server.
4. Commit and push to the configured branch. Confirm GitHub shows the file.
5. Choose Save and deploy on the existing app, or deploy the updated branch/commit with CLI or ARM.
6. Follow Versions and Deployments, then use Browse to verify the app.

If the error still appears, check the commit SHA in the new message against the commit you pushed, the configured app source root, and the exact filename. Changing a component's rootDirectory does not change where Builder looks for the app manifest. The source control guide explains how to change the app source root with CLI or ARM; the Portal does not provide a source-root editor. Use build and deployment diagnostics for any subsequent failure.

Health-check failures

Confirm the process listens on 0.0.0.0 and the declared port. For an explicit health path, return one of the configured status codes; the omitted list requires 200. Use a public path inside the component's URL prefix. Without an explicit path, a completed non-5xx response is reachability, not a functional test. DNS, connection, TLS, timeout, and 5xx outcomes fail that check.

PHP startup and document root

For the PHP 8.5 default runtime, omit run.start so nginx and PHP-FPM handle requests. Do not use a PHP development server as hosted startup.

If / or /health.php fails, confirm index.php and health.php are at the packaged build root. The default nginx document root is that build root, not an automatically selected public/ subdirectory. Check the component source root and Composer files separately from the generated output. For a custom build, stage the intended served files and required runtime dependencies under $DESTINATION_DIR; output is a static-only selector. Use run.healthCheckPath: /health.php and make that endpoint return HTTP 200. The default port is 8080 and a single component defaults to public mount /.

Commit and push corrections, request a new deployment, and follow it to completion before checking the active URL. See the PHP manifest example and runtime notes.

Authentication failures

Symptom	Check / action
App login endpoint reports misconfiguration	Authentication mode, enabled provider, target-managed provider setup
Customer-owned Entra sign-in fails	Confirm a user-assigned managed identity is assigned to the app, workloadIdentityResourceId names it, and the registration's federated credential matches the returned entraSetup values
Email rule denies a work account	Trusted tenant pins or verified xms_edov email evidence
Customer Entra API bearer rejected	Configured GUID audience, v2 access token, tenant/identity policy; not an ID token or ARM token
/.auth/me returns []	No accepted current identity, expired/rejected credential, or disabled authentication
/.auth/me returns 503	Authentication dependency unavailable; do not loop sign-in as if signed out
Concurrent authentication edit rejected	Refresh ETag and policy before retrying

Uncertain writes

A lost response can leave a save or deployment admitted server-side. Refresh source/identity state and inspect operation/history before retrying. Variable names cannot settle an uncertain value-only write. Retry identical deployment intent with the same request ID; a changed intent needs a new ID.

Get help

If these steps do not resolve the problem, check support availability.

Use the Portal or obtain the CLI through the installation guide. Deployments, authentication, and variables explain the related settings.