Common issues

Check these first when a framework adapter is wired but the dashboard does not show the run.

• No executions showing

  Confirm the wrapped route actually ran, FLUX_PROJECT_TOKEN and FLUX_PUBLIC_KEY are set on the server, and the server can make outbound HTTPS requests. Normal apps do not need FLUX_INGEST_URL.

• Replay or decrypt fails

  Set FLUX_PRIVATE_KEY on the server that exposes the agent route. Keep it server-only and redeploy or restart after changing it.

• Agent route returns unauthorized

  The dashboard sends a short-lived token to your agent route. Forward the Authorization header into fluxAgent and make sure the agent server also has FLUX_PROJECT_TOKEN.

• Browser request blocked by CORS

  Allow https://app.fluxrun.dev on the agent route and include Content-Type plus Authorization in Access-Control-Allow-Headers.

• Request body is empty

  Express and Koa need a body parser before the Flux adapter. Next.js, Fastify, Hono, Web Request runtimes, and Lambda adapters parse from their framework request objects.

• Custom ingest override breaks capture

  Remove FLUX_INGEST_URL and FLUX_INGEST_URLS unless you are using private or self-hosted ingest. The SDK already has production failover endpoints.

• Dynamic route params need explicit generics

  When using withFluxNextJs on a dynamic route like [id]/route.ts, add the type parameter: withFluxNextJs<{ params: Promise<{ id: string }> }>("..."). Otherwise flux.context.params is untyped.

• Middleware or auth guard needs original Request

  Pass { passRequest: true, mode: 'native' } to withFluxNextJs, then access the raw Request via flux.request.raw in your handler. Use fluxTrack for native recording.

• fluxHost.auto fails on typed interfaces

  Update to fluxrun@0.0.9+. Earlier versions required HostImpl (index signature); 0.0.9 accepts any Record<string, unknown>. For older versions, use the 54-method manual wrapping pattern.

Need fresh tokens or a new key pair? Open the dashboard.