Troubleshooting

”Action context factory is not configured”

Cause: setActionContext was not executed on server bootstrap. Fix:

app/bootstrap.server.ts

import { setActionContext } from "@zapaction/core";

setActionContext(async () => ({ userId: "demo" }));

Cause: missing or invalid readPolicy option. Fix:

components/panel.tsx

useActionQuery(listTodos, {
  input: {},
  queryKey: ["todos"],
  readPolicy: "read-only"
});

Cause: tag registry mismatch between tags and query keys. Fix:

app/providers.tsx

setTagRegistry({
  todos: [["todos"]],
  user: ({ input }) => [["users", input?.userId ?? "unknown"]]
});

Cause: useActionErrorReset was used outside boundary fallback. Fix: call the hook only inside fallback content rendered by ActionErrorBoundary.

terminal

pnpm build
pnpm typecheck
pnpm test