Troubleshooting

Common issues and how to fix them. If you are still stuck, open an issue on GitHub.

Tasks stay in pending and never run

  1. Check that the BullMQ worker is running: in your deployment, run pnpm worker.
  2. Verify REDIS_URL is set and the Redis instance is reachable from the worker.
  3. Check worker logs for connection errors. If Redis requires TLS, use rediss:// prefix in REDIS_URL.
  4. Confirm the agent has a valid model_provider and model_name set.

Provider health shows "unreachable" even with a valid key

  1. Make sure the environment variable is set in your deployment environment, not just locally.
  2. On Vercel: go to Project Settings → Environment Variables and confirm the variable exists for Production.
  3. All Vercel env vars have a trailing newline — the FleetRun SDK trims these automatically, but double-check the raw value.
  4. For Ollama (local), the NAS/GX10 must be reachable from the Vercel worker region (IAD). Local Ollama is not reachable from cloud deployments — use it only in local dev.

admin.fleetrun.app redirects to login instead of showing the portal

  1. The admin subdomain requires an active session. Log in at app.fleetrun.app first.
  2. The fr_session cookie is set on .fleetrun.app so it is shared across subdomains.
  3. If you are logged in but still redirected, check that FLEETMIND_SESSION_SECRET is the same value across all deployments.

Stripe checkout returns a 503 error

  1. The Stripe Price IDs have not been configured. Create products and prices in the Stripe dashboard.
  2. Copy the Price IDs (price_xxx) into Vercel environment variables: STRIPE_PRICE_STARTER_MONTHLY, STRIPE_PRICE_PRO_MONTHLY, etc.
  3. For annual billing, create separate annual prices and set STRIPE_PRICE_*_ANNUAL.
  4. Verify STRIPE_SECRET_KEY is also set and is the live key (not test) for production.

Stripe webhooks are not being processed

  1. Set STRIPE_WEBHOOK_SECRET to the signing secret from the Stripe dashboard (Developers → Webhooks).
  2. Register the endpoint https://app.fleetrun.app/api/billing/webhook in the Stripe dashboard.
  3. Required events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted.
  4. Vercel functions have a 10-second timeout — webhook processing is synchronous and must complete within that window.

Agent SSE stream does not show output in the terminal

  1. SSE requires the response to not be buffered. Vercel Edge Functions and serverless functions support SSE.
  2. Make sure the browser tab stays open — SSE connections close when the page is hidden on some browsers.
  3. If using Safari, try Chrome — Safari has stricter SSE handling.
  4. Check the browser Network tab: the /api/run endpoint should show a stream response with type: eventsource.

docs.fleetrun.app shows a blank page

  1. The docs subdomain is rewritten to /docs internally by middleware. Ensure the latest deployment is live.
  2. Clear your browser cache or try in an incognito window.
  3. Check the Vercel deployment logs for build errors in the /docs route.

Secrets vault shows "Decryption failed" for agent secrets

  1. ENCRYPTION_KEY must be a 32-byte (64 hex character) value and must be the same across all deployments.
  2. If you rotated ENCRYPTION_KEY, existing secrets encrypted with the old key cannot be decrypted. Re-enter them.
  3. Generate a new key with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Getting more help