Web publishing troubleshooting
Start with the JSON output from the failing stage and the private workspace manifest. Do not inspect or paste raw page bodies, tenant URLs, or credentials into an issue.
Refresh failures
Section titled “Refresh failures”| Symptom | Likely cause | Action |
|---|---|---|
page-unreadable or subtree-unreadable |
profile lacks view permission | fix access, rerun plan, or explicitly use partial policy |
page-version-changed |
page changed during discovery | rerun refresh; the version fence is working |
page-ambiguous-404 |
provider cannot distinguish deletion from restricted access | restore access or investigate before allowing deletion |
| asset blocked/missing | unsafe scheme, invalid bytes, or missing attachment | inspect the structured asset issue; never allow an unverified URL |
unowned internal URL '<base>/favicon.svg' or '<base>/' during verify |
the site template links to a file or page the build did not produce; Starlight links a favicon and the site root on every page | add public/favicon.svg and a root page (src/pages/index.astro) to the Astro project, or remove the link from the template |
Astro build failures
Section titled “Astro build failures”- Check that the project uses Astro
7.1.6or a supported 7.x release. - Ensure the project lockfile and build command are present.
- Ensure
astro.config.mjsreadsATLCLI_PUBLICATION_BUNDLE_PATHandATLCLI_PUBLICATION_INVENTORY_PATH; a fixed fixture/digest path becomes stale after the next successful refresh. - Keep
inventoryPathoutsidedistand remove only a deliberately stale, operator-owned output. - A failed build should leave the previous output untouched; if it does not, stop and preserve the workspace for investigation.
publication bundle does not match its digest(orpublication page '<id>' does not match its digest): a file under the active bundle directory was edited afterrefresh. The build recomputes every page and bundle digest before Astro reads them. Runrefreshagain; never edit a bundle.
Search failures
Section titled “Search failures”- Confirm
pagefind/pagefind.js,pagefind-worker.js, and index shards are in the private inventory and public output. - Keep
wasm-unsafe-evalin the CSP; do not replace it with broadunsafe-eval. - If a page still appears after deletion, rebuild the same output and inspect the semantic search manifest for stale source ids.
Verification failures
Section titled “Verification failures”- Unowned output: a theme plugin emitted a file outside the declared project/generated paths.
- Digest mismatch: output was edited after build or the wrong build digest was selected.
- Private URL/active content: content or a plugin emitted a forbidden sink;
remove it or add a safe renderer, never suppress the verifier. The verifier
inspects markup only: elements, attribute names and values, link and resource
targets, and inline scripts. Page text or inline code that mentions
onclick=,javascript:, or a Confluence REST path is content and passes, and so does a page whose route is/cache/,/bundles/, or/staging/. external resource/action,base element,meta refresh redirect, ordata URL: a template loads something from another origin or redirects away. Only<a>/<area>links and<link rel="canonical">or<link rel="alternate">may point off-site. Every other<link href>(stylesheet, preload, icon, manifest, font) and every SVG<image>/<use>target must be a file the build owns, likesrc: self-host fonts and stylesheets instead of linking a CDN.<base>is not allowed at all, and a<meta http-equiv="refresh">may carry a delay but no target.- Edit link outside the trusted Confluence origin: a template rendered an
data-atlcli-edit-linkelement that is not an<a>to the Confluence site the bundle was refreshed from. Render the value ofpublicationEditLinkV1(bundle, page.sourceId)unchanged; do not build a URL from a page ID. - Edit-link marker missing / in a page without a declared edit link: the
template renders the link on the wrong pages. Render it exactly when
publicationEditLinkV1returns a value. - Edit-link marker in disabled build: the template hard-codes a link while
editLink.providerisnone. - Different edit-link policy:
editLinkorvisibilitychanged after the lastrefresh. Refresh, then build again. - Edit links are enabled but a page has none: Confluence returned no usable
URL for it. With
fallback: "omit"a page without an edit URL gets no link;open-pagefalls back to the page view URL. The build manifest lists the pages undereditLinks.includedSourceIdsandomittedSourceIds.
Chart failures
Section titled “Chart failures”- Only a data table is visible: inspect
renderer-fallbackandimage-embed-faileddiagnostics. The table is the deliberate accessible fallback, not proof that the chart visual succeeded. - A chart is static in Astro: V1 hydrates only the proven Bar and XY Bar profiles within their row/series/point/byte budgets. Other shapes remain first-class server-rendered SVG.
- Strict refresh rejects a chart: fix the named malformed/locale/skipped-row source diagnostic or deliberately choose partial publishing; do not remove the diagnostic from the bundle.
See the complete chart troubleshooting matrix.
Getting help
Section titled “Getting help”Reproduce with --json, redact private values, include the operation, stage,
schema versions, and sanitized issue codes, and link to the relevant guide:
Jira and Confluence are trademarks of Atlassian Corporation Plc. atlcli is not affiliated with, endorsed by, or sponsored by Atlassian.