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 typically start in under a minute. If provisioning takes longer than 2 minutes:
  1. Check status: arga previews twins status <run-id> or poll the status endpoint.
  2. Inspect provisioning/runtime logs: arga runs logs <run-id> --errors-only.
  3. Cancel and retry with a fresh run
  4. If using the CLI wizard (npx arga-wizard), exit and re-run it
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.

​
”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.