Skip to main content

​
CLI authentication

​
”Not authenticated. Run arga login.”

The CLI can’t find a saved API key. This happens when:
  • You haven’t logged in yet — run arga login to authenticate.
  • The config file at ~/.config/arga/config.json was deleted or corrupted. Run arga login again to regenerate it.
  • The API key was revoked from the Settings page under Authorized CLI devices. Run arga login to create a new device key.

​
”Device code expired. Run arga login again.”

The browser approval window wasn’t completed in time. Device codes expire after 10 minutes. Run arga login again and approve the device in the browser before the code expires.

​
”Device code already used. Run arga login again.”

Each device code can only be used once. If you cancelled a login attempt or the flow was interrupted, run arga login to start a fresh authorization.

​
”Timed out waiting for authentication approval.”

The CLI waited 10 minutes for browser approval and gave up. Make sure you complete the approval at the URL shown in your terminal. If the browser didn’t open automatically, copy the URL and open it manually.

​
Test Run errors

​
”A valid public http(s) URL is required.”

Arga can only test publicly accessible URLs. This error appears when:
  • The URL uses localhost or a private IP address (e.g. 127.0.0.1, 192.168.x.x)
  • The URL scheme is not http:// or https://
  • The URL is malformed or unreachable
If you’re testing a local dev server, deploy it to a publicly accessible staging environment first, or use a tunnel service to expose it.

​
”A prompt is required.”

Every browser Test Run needs a prompt describing what to do. Add --prompt to your CLI command:

​
“Email and password must both be provided.”

You passed --email without --password or vice versa. Both must be provided together:

​
Need more detail from a run

Use the Test Runner commands to inspect a browser run:
Use --json for machine-readable output.

​
Run stuck in “queued” status

If a run stays in queued for more than a few minutes:
  1. Check the run: arga test-runner runs get <run-id>.
  2. Inspect its events: arga test-runner runs logs <run-id>.
  3. Start a new run if the worker did not begin.
  4. If the issue persists, contact founders@argalabs.com.

​
Plan limits

​
”Monthly free plan limit reached.”

Free plan users get 10 URL Test Runs per month. Limits reset on the first day of each month. Check your remaining usage with:
To get more runs, upgrade to the Team plan.

​
”Free plan allows 1 twin per run.”

Free plan users can provision one digital twin per short-lived Twin Run. To provision multiple twins together, upgrade to the Team plan.

​
”Automatic PR validation requires a Team or Paid plan.”

PR Test Runs and CI checks are Team plan features. Upgrade to enable repository automation.

​
”Team plan limit of N CI checks/month reached.”

Team plan includes 500 CI checks per month. If you need more, contact founders@argalabs.com about usage-based pricing.

​
Twin provisioning

​
”Quickstart API key has no provisions remaining.”

Your quickstart key (issued via email signup) is limited to 5 twin provisions and has been used up. Run arga login to authenticate with GitHub and get a full-access key with no provision limit.

​
Twins stuck in “provisioning”

Twin instances usually start in under a minute, but worker availability, startup, and scenario seeding can extend provisioning. If a run is still provisioning after 5 minutes, follow the steps below. Five minutes is a troubleshooting threshold, not a readiness guarantee or automatic failure deadline. A client timeout can expire while Arga is still provisioning. It does not mean Arga has reported a provisioning failure, and it does not cancel the run by itself.
  1. Keep the run ID returned when you created the Twin Run. Check the same run with arga twin-runs status <run-id> --json or poll the status endpoint.
  2. While the status is provisioning, continue polling within your chosen wait budget. Inspect progress with arga runs logs <run-id>; use --errors-only to focus on errors. Do not cancel and create a replacement solely because the client wait budget elapsed.
  3. Start testing only when the status is ready. If the API reports failed, inspect the returned error and logs, then request cleanup before retrying.
  4. If your wait budget expires, record a client wait timeout and check the latest API status. You can continue waiting for the same run or explicitly request teardown. If it makes no progress, contact founders@argalabs.com with the run ID, timestamps, last status, and relevant errors.
For a new run, set an explicit CLI wait budget. For example, this waits up to 10 minutes:
--timeout controls how long the client waits. It is not a readiness guarantee and does not extend the run’s TTL. Always inspect the returned status before starting tests; a completed CLI command is not proof that the run is ready. Set your CI job timeout long enough to cover provisioning, tests, and cleanup.
When a scenario_id or scenario_prompt is attached to a provision request, the status remains provisioning until twin seeding completes and seed_results are available. This is expected and ensures twins are fully initialized before the status transitions to ready.

​
Twins remain in “tearing_down” after teardown

Teardown is asynchronous. A successful teardown response with status: "tearing_down" means cleanup was requested, not that it has finished. This also applies when you cancel a run before provisioning completes.
Poll the status every 5–10 seconds until it becomes torn_down. If the teardown request fails or its response is lost, retry it with backoff using the same run ID. Repeated requests reuse active cleanup work. Give cleanup its own bounded wait budget. If the run remains tearing_down when that budget expires, report cleanup as unconfirmed and contact founders@argalabs.com with the run ID and timestamps. Do not treat failed, expired, or 404 Run not found as confirmation that cleanup finished. Use the same Arga account credentials that created the run. In CI, save the run ID immediately after creation and run teardown in an if: always() step, including when provisioning times out. Keep polling for completion and preserve the run ID if cleanup cannot be confirmed. A canceled CI runner may not finish this step, so keep a finite TTL as a backstop.

​
”At least one valid twin name is required.”

The twin names you provided don’t match any available twins. List valid twin names from the twin catalog or check spelling. Common twin names: slack, stripe, datadog, google_drive, google_docs, google_sheets, google_workspace, jira, and github.

​
Twins expired during testing

Short-lived Twin Runs default to 10 minutes on Free and 60 minutes on Team or Paid. If your twins expire mid-test:
  • Extend the session with arga wizard extend or the extend endpoint
  • Set a longer initial TTL (up to 480 minutes) when provisioning via the API directly
Re-run the wizard to start a fresh session.

​
MCP connection issues

​
MCP server not connecting in your IDE

  1. Verify you’re logged in: Run arga whoami to confirm your API key is valid.
  2. Reinstall MCP config: Run arga mcp install to rewrite the config files.
  3. Check the config file for your IDE:
    • Cursor: ~/.cursor/mcp.json
    • Claude Code: ~/.claude/mcp.json
    • Codex: ~/.config/codex/mcp.json
  4. Verify the API key in the config matches your current key (run arga whoami to see it).
  5. Restart your IDE after updating the MCP config.

​
MCP tools returning errors

If MCP tools return “Error: Not authenticated” or similar:
  • Your API key may have been revoked. Check Settings > Authorized CLI devices and run arga login + arga mcp install if the key was revoked.
  • The MCP config may have an outdated key. Run arga mcp install to refresh it.

​
MCP tools not appearing in your IDE

Some IDEs cache MCP tool definitions. After running arga mcp install:
  1. Restart the IDE completely (not just reload)
  2. Check that the arga-context server entry exists in the MCP config file
  3. Look for MCP connection errors in your IDE’s output/logs panel

​
GitHub integration

​
”GitHub not connected”

Open PR Test Runs, select the repository, and follow the prompt to install or authorize the Arga GitHub App.

​
”GitHub reauthentication required”

Your GitHub authorization has expired or been revoked. Open PR Test Runs and select Reconnect GitHub.

​
”GitHub integration required for validation.”

PR Test Runs require the Arga GitHub App on the selected repository. Install it from PR Test Runs before running arga previews pr-checks run or enabling a trigger.

​
Email verification

​
”Email is already verified”

The email address you submitted is already verified on your account. No action needed. Run arga whoami to confirm your verified email.

​
”Wait before requesting another verification code”

Verification codes can only be requested once per minute. Wait a moment and try again.

​
”Too many verification attempts. Request a new code”

You’ve used all 5 attempts for the current code. Click to request a new verification code and try again with the fresh code.

​
”No active verification code found for that email”

The verification code has expired (codes last 10 minutes) or was never requested for this email address. Request a new code and enter it within 10 minutes.

​
”Only one account can use an email address. This email is already linked to another account.”

Each email address can only be used by one Arga account. If you receive this 409 error when requesting a verification code, confirming a code, or signing up, the email is already in use on a different account. Sign in to the account that owns the email, or use a different email address.

​
”github_identity_already_linked” (during GitHub sign-in or repository setup)

The GitHub account you authorized — or the email returned by GitHub — is already associated with a different Arga account. Sign in to the original account, use a different GitHub account, or contact founders@argalabs.com if the old account is inaccessible.

​
General

​
Network errors

If you see “Network error” from the CLI, check:
  1. Your internet connection
  2. That https://api.argalabs.com is reachable: curl https://api.argalabs.com/health
  3. If using a custom API URL (--api-url or ARGA_API_URL), verify it’s correct

​
Something else?

If your issue isn’t covered here, reach out at founders@argalabs.com.