Troubleshooting

Hit a DEFER_* error? Match the code below. Public defer failures use CruxDeferError with a stable code and docsUrl (https://cruxjs.dev/docs/errors/<CODE>).

import { CruxDeferError, defer } from '@use-crux/core'

try {
  defer(() => {})
} catch (error) {
  if (error instanceof CruxDeferError) {
    console.error(error.code, error.docsUrl)
  }
}

Quick map

Runtime-bound failures still use Runtime codes such as RUNTIME_REQUIRED.

Checklist

1. Is the handler wrapped (withNodeDefer, withNextDefer, withWaitUntilDefer, Convex bridge.run, …)?
2. For inline work: does the host advertise a real lifetime capability?
3. For named work: is config({ runtime }) present and is durableFinalization: true on the host lifetime?
4. Inside flows: use flow.defer(), never public defer().
5. Catching a named defer promise does not undo DEFER_COMMIT_FAILED; fix the staging failure or use the callback overload for best-effort work.

Project Index lints

Static analysis reports:

• defer.replay_unsafe
• defer.floating_named_promise
• defer.missing_scope

Named calls without Runtime also reuse runtime.missing_runtime_config when the analyzer can tell for sure from your code. Static analysis cannot always determine host capability; the runtime still throws DEFER_CAPABILITY_MISSING when the live host cannot honor the call.

Check project setup

Run crux setup for a read-only aggregate check, or crux setup --apply to apply safe additive Runtime resources and recheck. The defer contributor reports missing host integrations and named-durability configuration with exact remediation and a privacy-safe coding-agent prompt. Lifetime capability is still verified at the live host boundary; having a package installed does not by itself mean the host supports defer.

See Project setup for modes and JSON output.

Related

• Host matrix
• Error catalog