Validation & Preflight

Before a work goes live, Preflight Validation checks it for problems — missing translations, broken navigation, oversized files, accessibility gaps. Errors block publishing; warnings and info items are advisory.

You reach it in two ways:

• The Preflight button in the editor header (it shows a badge with the current issue count).
• Validation in the Backstage sidebar, which opens the full Preflight Validation page.

Publishing runs the same checks: the publish wizard's first step is Preflight.

Running a validation

Click Run Validation. When it finishes you get a summary:

• A verdict card — Ready to Publish (green) or Cannot Publish (red) with the total issue count. If you've run validation before, a diff shows how many issues are new and how many were resolved since the last run.
• Counts per severity: Errors, Warnings, Info.

What is checked

Issues are grouped into nine categories:

An issue whose category the preflight does not know is listed under an extra Other group, so the list always matches the counts in the summary. Other appears (also in the Category filter) only while it has issues; its re-run button re-runs the full validation.

Working through issues

Issues are listed grouped by category. Each row shows a severity badge, the human-readable message, and the issue code (e.g. MISSING_ALT_TEXT). Click a row to open the details:

• Path — where in the work the problem sits (with a copy button), plus panel/bubble IDs and locale where relevant.
• Suggestion — the recommended fix.
• Used in — for asset issues (missing alt text, oversized asset), one link per chapter/page/panel that displays the asset; each opens that panel in the editor. Assets not placed on any panel say so — manage those in the editor's Assets tab.
• Open in editor — jumps straight to the offending panel so you can fix it.
• Learn more — opens the matching section of the Validation Code Reference, which documents every issue code with its severity and recommended fix.

To narrow a long list use the Search box (message, code, or path), the Category dropdown, and the Errors / Warnings / Info severity toggles. Frequently used filter combinations can be saved as presets (Save current as preset) and re-applied with one click.

Each category header also has a re-run button so you can re-check just that category after fixing things.

Auto-fixes

Issues that can be fixed automatically show a Fix button:

You can also:

• Tick multiple fixable issues (or select a whole category) and click Apply fixes to selected.
• Undo the most recent applied fixes — removed content is restored from a snapshot taken just before the fix, so undoing a page clean-up puts back exactly that page.

Optimizing oversized images

Images over the 5 MB publish limit get their own fix: an Optimize button on each oversized-image error, plus Optimize all (n) on the group. Optimizing runs in the background — the CMS re-encodes the image as WebP, stepping down quality (and, if needed, resolution) until it fits the budget — and the issue list polls until the queued jobs finish and the errors clear on their own.

• Your original stays untouched in the library at full quality; the fix adds an optimized variant, and the published work ships that variant instead.
• The size check judges the effective shipped size, so an already-optimized image doesn't get flagged again.
• Undo removes the optimized variant and restores the previous state.

Fixing common issues

The Validation Code Reference covers every code individually; the most frequent ones:

Exporting a report

Export JSON and Export CSV download the full issue list — useful for tracking fixes in a spreadsheet or handing a QA report to teammates.