Askr
Reference

Troubleshooting

Use troubleshooting with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use troubleshooting

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.

  1. Import the published @askrjs/askr entrypoint.
  2. Keep troubleshooting configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
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' dist

Hydration 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 @askrjs/askr/testing's `matchRoute()` and `getRouteWarnings()` against your real manifest — 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.