Validation Errors

This page covers errors from all three validation surfaces: AJV directly, the panelwave CLI, and the CMS Preflight Validation.

AJV won't even compile the schema

Symptom: errors like no schema with key or ref "https://json-schema.org/draft/2020-12/schema".

The schema uses JSON Schema draft 2020-12, which the default AJV build doesn't support. Use the 2020 build:

const Ajv2020 = require('ajv/dist/2020');
const addFormats = require('ajv-formats');

const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);

Full setup: Validating Manifests.

"must NOT have additional properties"

The most common error. Nearly every object in the schema is closed (additionalProperties: false), so this means one of:

• A typo in a property name (chapers instead of chapters).
• A property at the wrong nesting level (e.g. transition directly on an edge's condition).
• Custom data without the x- prefix — and note x- fields are accepted only at the manifest root, on panels and on extras blocks (the last two since format 1.7), not on other nested objects. See Extensions.

The error's instancePath tells you exactly which object carries the offending property.

"must NOT have fewer than 1 items" on graph.edges

Before format 1.7, every chapter graph required at least one edge, so a single-panel chapter with "edges": [] was invalid. Since 1.7.0 edges may be empty (the chapter follows its reading order), so this error only appears when the manifest is validated against an older (1.0–1.6) schema copy — update @panelwave/cli or add a second panel and an edge. See Graph.

Missing required properties

A manifest requires panelwave, meta, and chapters at the top level. Within meta, the required fields include id, title, locales, and default_locale. The error message names the missing property; the Manifest Structure page shows a minimal valid manifest to compare against.

"must match pattern" on variable IDs

Variable IDs are stricter than other identifiers: they must match ^[a-zA-Z0-9]+(?:\.[a-zA-Z0-9_-]+)*$ (dot-namespaced, e.g. story.hasKey), and plugin state variables must start with plugin.. See Variables.

CLI warnings (exit 0, but flagged)

panelwave validate emits structural warnings that don't block validation unless you pass --strict:

• No "assets" section — panels referencing assetIds will fail at runtime.
• No "characters" defined in meta — speech bubbles with characterId will be unresolved.

CMS preflight says "Cannot Publish"

The CMS runs deeper checks than the schema: broken references, duplicate IDs, unreachable graph nodes, missing captions/alt text, oversized assets, and more, grouped into nine categories (plus an Other group for anything uncategorized) with three severities. Only errors block publishing. Each issue includes a suggestion, an Open in editor shortcut, and often an auto-fix. See Validation & Preflight for the workflow and the Validation Code Reference for what each issue code means and how to fix it.

Import into the CMS fails

The work import accepts manifests declaring a panelwave.version from 1.0 to 1.7 (patch and pre-release versions such as 1.7.1 included) and at most 10 MB of JSON. A newer format is rejected with "This manifest uses format X; this CMS supports 1.0–1.7.", a missing or malformed version with "This manifest has no valid format version (…); this CMS supports 1.0–1.7." See Import.