# Build, upload, and deployment failures | answer.cloud Docs

> Canonical source: [Build, upload, and deployment failures | answer.cloud Docs](https://www.answer.cloud/docs/troubleshooting/deployments/)

Resolve artifact, upload, finalization, destination, and stale-release problems while preserving the intended site and avoiding duplicate deployment starts.

troubleshooting

Build, upload, and deployment failures

Resolve artifact, upload, finalization, destination, and stale-release problems while preserving the intended site and avoiding duplicate deployment starts.

Reviewed November 1, 2026

Start by inspecting `get_deploy` for the existing numeric deploy ID. Record its site, sequence, environment, status, warnings, and any returned live URLs. A lost response or a slow pipeline does not mean another deployment is necessary.

## Check the artifact

Build the editable Astro source and package the contents of its output directory. `index.html` belongs at the ZIP root, alongside required assets. Include the CMS manifest and private templates when the site uses them. Exclude credentials, dependency folders, and unrelated archives.

A ZIP containing `dist/index.html` rather than `index.html` has the wrong root layout. A client-only shell can deploy but trigger `spa_shell` and poor retrieval. An omitted image or stylesheet remains omitted from the new artifact.

`deploy_files` also creates a fresh artifact from only its supplied files. It does not merge changed files into the previous release. Use it only when the entire required tiny artifact fits its 512,000 decoded-byte ceiling; use the ZIP workflow for a complete normal website.

## Recover the existing upload

| Observation                         | Action                                                                                  |
|-----------------------------------|-----------------------------------------------------------------------------------------|
| `uploading`, artifact already uploaded | Finalize that deploy ID.                                                                |
| `no_artifact`, saved URL still valid | Upload the binary ZIP to that exact URL, then finalize the same ID.                      |
| Lost/expired URL, artifact may exist | Try finalizing the existing upload before starting another.                              |
| No artifact and no usable upload URL | Start a replacement deploy on the same site within remaining quota.                      |
| `too_large` at finalization         | The oversized object was deleted; reduce the artifact before re-uploading.              |
| `failed` with a usable artifact/URL | Correct the cause and use supported re-upload/re-finalization on that record.            |
| `queued` or another processing state | Poll using `retry_after_seconds`; do not re-finalize.                                   |

The signed URL is private and lasts 900 seconds. Send actual ZIP bytes using HTTP PUT, not JSON or base64 text. Inspect upload status before finalization. Keep size under returned `max_bytes` and preserve the artifact checksum when verifying integrity.

## Check release routing

A deployment can be live in staging while production still serves an earlier release. Inspect the site's release workflow and deployment pointer flags, then verify `live_urls`. Explicit deploys require a supported destination. Staging/both need an active release workflow; production in that workflow needs an active custom domain.

If the expected content is absent, compare the source build, artifact, selected environment, and actual public URL. Inspect the response after ordinary cache propagation rather than immediately rebuilding an identical artifact. CMS text may be republished independently of the static source.

## Verify recovery

Read every actionable warning, including skipped pages, CMS collisions, and social-preview problems. Open key pages and assets, confirm the new factual content in HTML, and test a meaningful chat response. Record the final deploy ID/sequence and destination.

For exhausted quota or expired guest access, preserve source and use [account recovery](https://www.answer.cloud/docs/account/access/). For a persistent platform failure, send [support](https://www.answer.cloud/docs/account/support/) the safe deploy identifiers and exact error; never include the signed upload URL.