Troubleshooting
Troubleshooting means matching what you see (a symptom) to what to try next — without guessing or opening a support ticket first. Use this page when X4RGE does not behave the way you expect: sign-in, GitHub, a cloud agent run, or the desktop app after login.
Most issues are access, organization policy, integration setup, or network — not a broken product. A few checks often fix them in minutes.
Press ⌘K (Mac) or Ctrl K (Windows) to search the rest of the docs, then use the tables below. Same self-service pattern as other agent platforms: fix the common cases yourself, escalate only when needed.
What this page is for
Start here
Search the docs
Try different keywords — "GitHub", "budget", "sign in", "cloud agent".
Pick your symptom
Use In practice or jump to the section that fits.
Try the fix
Follow the steps in that section. Change one thing at a time so you know what helped.
Escalate if needed
Use Who can fix what — admin for policy, support for product bugs.
In practice
Pick the row that sounds like your situation, then open the linked section.
Who can fix what
Knowing who to ask saves time. Try the section fixes first; use this table when you need someone else.
Organization admins use the same symptom tables when helping their team — plus the dashboard for members, usage, and integrations.
Sign-in and access
Sign-in problems usually mean the wrong entry point, no org membership yet, or a desktop handoff that did not finish. Work through these in order.
Use the right sign-in flow
Sign in from the product you use — dashboard, desktop app, or CLI — and complete auth in the browser if prompted.
Check organization access
If you land on a no-access page after sign-in, you may not be in an organization yet. Ask an admin to invite you from Members.
Desktop return to IDE
If the browser does not hand off back to the IDE, see Deeplinks and try signing in again from the app.
Integrations
Integrations connect X4RGE to tools you already use. GitHub is fully supported today; Slack and Linear may appear in the UI before connect is finished — see below.
GitHub
See GitHub integration for setup steps.
Slack and Linear
Cloud agents
Cloud agent issues usually fall into three buckets: spend policy (budget or plan), model policy (admin allowed list), or environment (install commands and network inside the run). Check which message or status you see, then try the matching row.
For support, copy the run ID from the Agents workspace. See Help & support.
Pair with Cloud agent setup and Security & network if installs fail inside the cloud environment.
Network and firewalls
If X4RGE works on your home network but not at the office, your company VPN or proxy may block outbound HTTPS. You cannot fix this alone — share the list below with IT.
Ask your network admin to allow HTTPS to:
Full egress guidance for cloud sandboxes is in Security & network. Test from the same network your developers use.
Desktop and CLI
The desktop app and CLI sign in through the browser, then hand control back to your machine. Failures here are almost always handoff, session, or org policy — not your code.
See CLI overview and Headless CLI for install and CI auth.
Still stuck?
You tried the section that matched your symptom and it did not help. Escalate with context so support or your admin can reproduce the issue quickly.
- Help & support — full escalation guide and response expectations.
- Organization admin — if the issue is access, budget, models, or GitHub on your org.
- support@x4rge.ai — product bugs and sign-in after the steps above.
Include: organization name, run ID (for cloud agents), exact error text, what you expected, what you already tried, and when it happened.