Troubleshooting

This page collects the most common issues across local development, sign-in, integrations, cloud agents, and corporate networks. Search the docs first — press ⌘K (or Ctrl K) — then work through the relevant section below.

Search the docs

Press ⌘K (or Ctrl K) and type what you're trying to do. If search doesn't open, refresh the page and try again.

Local development ports

Each app uses a fixed port so nothing collides. If a dev server fails to start with a port error, stop the process using that port or pick the correct app:

Common local setup mistakes

Sign-in and authentication

1. Confirm authenticator is running

   The authenticator app must be reachable at the URL in your app's NEXT_PUBLIC_AUTH_URL (port 3003 locally, auth.4rged.ai in production).

2. Verify Supabase env vars

   Each app needs NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY pointing at the same Supabase project.

3. Check org membership

   After sign-in, if you land on a no-access page, ask an admin to invite you from Members.

4. Desktop handoff

   If the browser doesn't return to the IDE, see Deeplinks.

Integrations

GitHub

• Shows connected but repos don't sync locally — full repository sync requires the Supabase service role key (SUPABASE_SERVICE_ROLE_KEY) in your local agents-api environment. Without it, the GitHub app connection succeeds but repository metadata sync is limited.
• Webhook deliveries failing — confirm GITHUB_WEBHOOK_SECRET matches the GitHub app config and the agents API is reachable from GitHub (use ngrok locally).
• PR creation denied — verify the GitHub app has write access to the repository and branch protection allows the bot account.

Slack and Linear

See Slack and Linear for planned capabilities.

Cloud agents

Start a debug run

curl -X POST "http://localhost:3008/api/agent-runs" \
  -H "Authorization: Bearer <session-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_local",
    "repositoryId": "1",
    "prompt": "Print node version and exit",
    "agentKind": "cloud"
  }'

Cloud agents and network

If you're behind a corporate firewall or proxy, outbound traffic to 4RGE services may be blocked. Allowlist these domains (HTTPS unless noted):

See Security & network for the full allowlist and operator checklist. Ask your network admin to test from the same VLAN as developer machines.

Console and provisioning

Docs site validation (contributors)

If you edit documentation in apps/docs/content, run npm run validate:content from apps/docs before opening a PR. The script checks _meta.json navigation manifests, verifies every listed page exists, and validates MDX frontmatter (title, optional description) with Zod. Missing files or empty titles fail CI locally — fix manifest paths before pushing. The docs app serves on port 3002 (npm run dev:docs); production docs live at docs.4rged.ai.

Still stuck?

See Help & support for who to contact — your org admin for access and policy questions, or support@4rge.ai for everything else.

When contacting support, include:

• Organization ID and affected repository
• Run ID or automation ID (if applicable)
• Timestamp and error message
• Whether you're on a corporate network or VPN