Troubleshooting and verification
Isolate installation, loading, syntax, resources, extensions, saves, and distribution failures.
Save your work and start with the earliest meaningful source-level error. Reinstalling Node, rewriting the manifest, and regenerating identities at once makes it difficult to identify the real cause.
Installation and startup
| Symptom | First check |
|---|---|
npm cannot find @prismatix/cli / E404 | Is this candidate publicly published, or do you need the maintainer's registry? |
| prismatix is not found | Global installation and terminal PATH; use npm exec inside a prepared project |
| Destination is rejected | Existing files, read-only directories, or symlinks; never overwrite existing work |
| Native runtime is missing | Matching platform/version bundle; do not mix an unrelated Player release |
| Global CLI works but local tools fail | Restore pinned CLI/SDK dependencies from the lockfile |
| Paths with spaces fail | Quote the entire path |
Initial create requires a registry, unlike dev/build after preparation. If interrupted creation leaves staging/lock data, first check whether a create process is still active and follow the actual diagnostic. Do not bulk-delete unfamiliar directories.
Project and Story failures
prismatix validate my-game
prismatix validate my-game --jsonPXCLI1001 indicates loading trouble: check JSON, manifest selection, and referenced files. PXCLI1101 is a broad build failure; read earlier, more specific diagnostics. PXCLIJSX1002 concerns TSX evaluation: check the default export, imports, and native UI types rather than treating it as Story syntax.
PXSTORY1199 usually means an unknown command: a typo, unregistered extension, or syntax belonging only to the internal VM or another engine. Explicit-ID problems use PXSTORY1210–1213. Regenerating every identity is not a safe way to conceal duplicates or dangling IDs.
Unexpected narration often comes from a blank line ending speaker scope. Unexpected dialogue often comes from an active @guide without a blank line. If one branch continues into another, inspect label fall-through and explicit jump/end instructions.
Preview does not update
Check terminal diagnostics first. Retaining the previous playable Preview after an error is intentional, not automatic evidence of a broken watcher. Fix the reported source, save it, and confirm acknowledgment of the new revision.
Restarting the scene after successful edits is also the current policy, not a promise of preserving a JavaScript heap across hot updates. The watcher can recover from initial loading errors after repair. Use Ctrl+C to exit rather than accumulating competing Preview processes.
Missing images, audio, or glyphs
Check safe relative paths, casing, file existence, asset descriptors, expression assetId mappings, codecs, and glyph coverage. Declaring a resource does not download it, and changing locale does not translate content or install every font.
If extra Story volume/fade arguments do nothing, verify that the compiler actually lowers them. Use runtime APIs for advanced audio controls. Unsupported shaders or video in WASM/basic graphics tiers are capability issues, not necessarily filename mistakes.
Extension callbacks do not run
Check project.extensions, manifest.entry, modules, command/action IDs, casing, parameters, capabilities, and generated JavaScript. Story commands and UI Actions are not interchangeable.
Did you rebundle after editing TypeScript? Does the output still contain an unresolved @prismatix/runtime import, node:fs, DOM access, or require? The runtime is not Node.js. Adding a capability does not grant arbitrary OS permissions. Validation also does not execute every callback; play through the corresponding Story operation.
Saves and refused output replacement
Preview slots do not persist after rebuilding the session. For packaged Player restore failures, inspect contentVersion, saveVersion, Story anchors, data types, and state-provider versions instead of blaming every failure on one ID.
When a build refuses to replace a modified output folder, use a fresh destination and preserve existing data. Do not delete player saves to satisfy ownership checks. Moving only the executable can also lose packaged content, libraries, and licenses.
Report a reproducible issue
Include the engine/package version or commit, OS and CPU architecture, Node/npm versions, exact command, complete first error with source location, and a minimal project without private data. State whether the failure occurs in validate, native Preview, WASM Preview, or the packaged Player.
For visual/audio failures, include actual observations, not only a test-success message. For saves, use isolated fixtures and explicit old/new versions. Remove secrets, personal absolute paths, and assets you cannot share.
Verification boundaries of this handbook
Chapters link to a pinned engine snapshot and distinguish complete files, merge fragments, and examples needing external resources. The documentation integrity check covers matching chapters, navigation, JSON fences, and the tutorial extension fixture. It is not the engine compiler and does not replace native Player end-to-end tests.
Sources: CLI, Story diagnostics, Author workflow, Runtime SDK.