Troubleshooting
Troubleshooting: published entrypoints, signatures, and the constraints around them.
Example
Reduce failures to the owning boundary: confirm package alignment, reproduce with the production renderer, inspect route output, then add a regression test before changing code.
npm ls '@askrjs/*'
npm run typecheck
npm run build
# For SSR or SSG, inspect the generated HTML before debugging hydration.
rg 'data-askr|<main|<title' distHydration mismatches
If the client's first render doesn't match the server-rendered markup byte-for-byte, hydration can attach event handlers to the wrong nodes or throw outright. The usual culprits are non-deterministic output during render — Date.now(), Math.random(), or environment checks like typeof window — used directly in a component body instead of behind an effect or resource that only runs after mount.
Package skew
Type errors that don't match what a package's own README shows, or props/exports that seem to be missing, are frequently a version-skew problem rather than a real API gap — since @askrjs packages version independently, check that your installed versions of @askrjs/askr, @askrjs/ui, @askrjs/themes, and @askrjs/server line up with what's documented here before filing a bug.
Routing and SSG
A route that 404s unexpectedly, or two routes silently shadowing each other, is best diagnosed with matchRoute() from @askrjs/askr/router and getRouteWarnings({ registry }) from @askrjs/askr/testing against the same explicit RouteRegistry your app uses — the latter flags route-collision warnings with the conflicting path and segment directly. For SSG output missing a page, check that the route's entries generator (used to enumerate static params) is actually returning the param combination you expect.
Server and network failures
Because resource() and query fetches receive an AbortSignal tied to the owning component, a failure that looks like a silently swallowed network error is often just cancellation — the component unmounted before the request resolved, and the abort was legitimate. For actual server-side failures, check the handler registered through @askrjs/server's router/middleware subpaths, since those run independently of the client's render and won't show up in browser-side error boundaries.