When an export fails

Manuscrio is deliberately fail-closed: it would rather stop than publish a manual with content missing from it. This page covers what it reports, and what each report means.

Problems appear in two places. inspect reports what discovery noticed about the Site Build, and never fails because of it. export reports what happened while rendering, and stops the run.

Paths in these messages are the ones inside the container — /input for the Site Build, /output for the PDFs — whichever way you started the run.

The framework was not recognised

Could not recognise the documentation framework in Site Build: /input
Supported: docusaurus, starlight, mkdocs. Pass --framework <name> to skip detection, and check
that this directory is a finished static build rather than a source project.

Detection reads the built pages for each framework’s article marker. The two usual causes are mounting a source project instead of the directory its build produced, and a theme that does not emit the markup the adapter binds to — an MkDocs build using a theme other than Material, for instance. --framework <name> skips detection, which is worth trying to see the more specific error underneath. See supported frameworks.

Discovery diagnostics

Each entry in the diagnostics array of the inspect report carries a code, a message, and the routes it concerns.

UNLISTED_PAGES

Rendered documentation pages exist in the build that no sidebar links to.

A Manual follows the print navigation, so these pages are not exported. This is usually correct — the pages are drafts, redirects, or deliberately hidden — but it is worth reading the route list once for a site you have not exported before, because a sidebar misconfiguration looks exactly the same from outside.

To include such a page, link it from the sidebar in your documentation source and rebuild.

UNASSIGNED_DOCUMENTATION_SET

A sidebar belongs to no unambiguous documentation-bearing navbar entry.

This one has teeth. Where an edition has navbar sections, its manuals are composed from those sections, so a sidebar attributed to none of them would be dropped from the manual without anything saying so. Manuscrio refuses instead:

Edition default:en:current contains unassigned documentation sets; use --scope sidebar-root

The message is raised while planning, before anything renders, so the run stops at both --scope edition and --scope section rather than producing the other editions’ manuals. --scope sidebar-root plans normally, including a manual for each root of the unassigned sidebar, because at that scope nothing depends on which section a root belongs to.

You have two ways forward, and they answer different questions. Export at sidebar-root scope if the content is fine and you want it now. Make the sidebar reachable from a navbar entry in your documentation source if it should have been part of a larger manual all along — the diagnostic is usually a navbar configuration that drifted, not a Manuscrio limitation.

This diagnostic does not arise for a site whose navigation has no section level at all. Starlight and MkDocs builds report every sidebar as unassigned for that reason, and export in full at edition scope; see the note in supported frameworks.

Export failures

An export renders manuals independently. Every manual that succeeds is written to the output directory and logged with its path; the run then fails at the end, naming only the manuals that did not finish. A partial run is therefore still useful, and rerunning with --manual <id> limited to the failures is a reasonable next step.

Content clipped out of the page area

[print-export] CONTENT CLIPPED (3) in <manual-id> — this text will be missing from the PDF:
    ...

Geometry is checked before the PDF is produced, because content outside the page box is discarded by the browser and cannot be detected afterwards. At most 25 items are listed, followed by a count of the rest.

The usual cause is a layout the paginator cannot break across pages: a CSS grid, a wrapping flex column, or a box whose overflow is not visible. The content is present in the HTML and lost only in print, so the fix belongs in the documentation source or in the theme.

A separate line reporting lines “marginally over the content box (cosmetic)” is informational. It does not fail the export.

--no-fail-on-clipped downgrades the fatal check to a report. Use it to see the full picture while diagnosing, and do not leave it in a release pipeline: it is exactly the setting that lets a green job publish an incomplete manual.

Blocked by browser or runtime issues

[print-export] FAILED <manual-id>: Export blocked by browser/runtime issues: [response] HTTP 404 ...

Manuscrio treats a page that could not fully load as a failed manual rather than rendering it partially. The prefix identifies what happened:

Prefix	Meaning
[response] HTTP <status>	A resource the page requested answered with an error status.
[requestfailed]	A request did not complete at all.
[pageerror]	A script on the page threw.

The most common real-world case is an external asset a documentation page embeds by absolute URL — an image on a third-party host that has since moved, been removed, or started answering with something that is not an image. Nothing in the Site Build changed; the internet did.

There is no flag that renders past it. Either fix the reference in your documentation source, or export a narrower scope: the failure is contained to the manuals that include the offending page, and the others still export.

Layout errors

Problems containing unable to layout or Layout repeated also write a debug screenshot beside the intended PDF, named after it with a -debug.png suffix. Open it to see the state the paginator was in when it stopped.

Licence failures

A missing licence is not a failure — it selects Evaluation Mode. A licence that is present but cannot be honoured, because it is unreadable, invalid, or more than thirty days past expiry, fails the run before any work starts.

The most common cause in a container is file permissions rather than the licence itself: the image runs as its own user and cannot read a licence file that belongs to you and is mode 0600. Both runtimes use --user "$(id -u):$(id -g)"; rootless Podman also needs --userns=keep-id, as the container invocation page describes.

Run manuscrio license to print the entitlement an export would use, without exporting anything.

Reporting a problem

Include the inspect output for the Site Build, the full export log for the failing manual, and the exact command. The log names the framework it detected, the theme, the brand logo it found, and the page count of every manual it rendered, which is usually enough to reproduce the run.