Troubleshooting

Use this checklist before changing code to work around an environment issue. Capture the failing command and first meaningful error, not only the last line of output.

Source HTML has no styling

Run npm run dev and open the printed URL. Source HTML contains build-time partials and TypeScript imports; opening a root file directly is not equivalent to the compiled theme.

For a release preview, run npm run build followed by npm run preview. Serve the complete output, including assets, rather than moving one HTML file. If text such as {{> sidebar}} appears in the browser, check that you are not serving unprocessed source through another static server.

Installation or build fails

Confirm you are in the folder containing package.json and use the lockfile supplied with that source revision:

node --version
npm --version
npm ci
npm run build

If Node is rejected, compare it with the installed Vite package's engines range. Do not remove the lockfile or weaken TypeScript checks to hide a failure. For a TypeScript error, open the reported source file and resolve the actual type or missing import. If a partial cannot be found, compare its placeholder name with the file in src/project/partials/.

Preview server stopped

The development server is a foreground process. If its terminal closes, restart it:

npm run dev -- --port 5200 --strictPort

If the port is already in use, inspect the existing process before starting another server; do not terminate an unknown process blindly. Browser tests use port 5198. Avoid concurrent suites and source edits during tests, which can cause page reloads and misleading failures.

A new page is missing from the build

Check the non-documentation input list in vite.config.ts. Vite can serve a root HTML source file in development even when it has not been registered for production. Register the page, rebuild, then open its compiled URL directly. Confirm new navigation links use the same filename and case.

A style or asset is missing

Confirm the page imports the project stylesheet through its module entry and that a competing dark-theme selector is not overriding the intended token. Use complete Tailwind class names in scanned source rather than constructing fragments at runtime.

For public assets, the URL starts at the output root: a source file public/assets/example.webp becomes assets/example.webp, not public/assets/example.webp. Check the network panel for the actual failed URL and filename case. Avoid root-absolute page links on path-prefixed hosts. Standalone documentation excludes public/; a file available in the full theme may not exist there.

A demo action does not save

Most interactions are intentionally in-memory previews. Reloading resets chat messages, approvals and account changes. Sidebar pins and collapsed groups are browser-local preferences, not account data. Private browsing, blocked storage or another browser profile may produce a fresh sidebar state.

Review the page notice and controller before assuming a backend exists. A simulated success message, paid badge or accepted invitation does not prove an external action occurred. Do not enter real secrets into example forms.

Browser tests do not start

Install the required browser if Playwright reports a missing executable:

npx playwright install chromium
npm run check

The complete check prepares theme and documentation outputs. If running npm test alone after a clean checkout, build both first for tests that inspect compiled documentation. Confirm port 5198 serves this project; the configuration can reuse an existing server on that port. Rerun a single failing spec while diagnosing, then run the complete suite once the cause is fixed.

A documentation link fails

Check that the article is registered in scripts/documentation.mjs, its source stub exists and its Markdown heading matches the fragment. Rebuild documentation after edits. Heading changes also change generated anchors and Jump to entries.

Verify the deployed directory contains its assets and the documentation/ folder. Test a direct article URL and a copied heading link under the real path prefix. The local dev server is not sufficient evidence of correct hosting paths.

Before contacting support

Include the page URL, browser and version, viewport, reproduction steps, expected behavior and exact build/test command output. State whether you used development source, compiled preview or a deployed build and describe any customer modifications.

Remove tokens, personal data and private project details. Supply a minimal reproduction and a screenshot of the relevant state rather than sending an entire production project. Keep a copy of your changes before attempting a proposed fix.