Troubleshooting

Five problem areas, each with a cause and a fix. Start with the area that matches the symptom.

Build fails

A build that fails on dependencies usually means the wrong Node version or a partial install. Confirm Node.js 20 or newer, delete node_modules/, and run npm ci again. A build that fails on a page usually names the page and the missing import; check that the import path matches the file on disk, including case.

Storage

Kestrel keeps almost nothing in browser storage: the theme preference only. If a page behaves oddly after an upgrade, clear the site's stored data in the browser and reload; every page rebuilds its state from its own content.

Theme

The theme preference lives under the storage key kestrel-theme, with values light and dark. A theme that sticks after toggling usually means a stored value from an older build: remove that key and reload, and the site falls back to the system preference.

Forms

A form that does nothing on submit is almost always an adapter problem. Check the adapter value in the form configuration against the adapters in the Customization docs: demo sends nothing by design, and mailto needs a mail program on the visitor's device. A form with no adapter configured, or with an adapter name that matches nothing, drops submissions silently; give it an adapter before anything else.

Routes

An unknown path shows the 404 page with the text "This route is not in the map." That is the correct behavior for a path outside the route map, not an error to fix. If a path that should exist shows the 404 page, check the route map: the page file must exist under src/pages/ and the build must have generated its output under dist/. Rebuild after adding or moving a page.

Back to the documentation index.