# Troubleshooting

> Troubleshooting: published entrypoints, signatures, and the constraints around them.

Source: [https://askrjs.com/docs/reference/troubleshooting](https://askrjs.com/docs/reference/troubleshooting)

Status: stable. Packages: @askrjs/askr.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## 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.

```sh
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({ registry })` 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.

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/glossary/index.md) | [Next](https://askrjs.com/docs/reference/api/askr/root/index.md)