Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

Free plan users must provide a test prompt describing what to validate. Add --prompt to your CLI command: 
arga test-runner runs url --url https://your-app.com --prompt "test the login flow"
Team plan users can omit the prompt — Arga will auto-plan tests based on the application.

​
”Email and password must both be provided.”

You passed --email without --password or vice versa. Both must be provided together: 
arga test-runner runs url \
  --url https://your-app.com \
  --prompt "test the checkout flow" \
  --email test@example.com \
  --password your-test-password

​
Need more detail from a run

Use arga runs logs to retrieve the current logs snapshot for a validation run: 
arga runs logs <run_id>
arga runs logs <run_id> --errors-only
--errors-only keeps failed worker logs and warning/error runtime logs. Use --json for machine-readable output. The response can include warnings, and large worker logs may be truncated. For the full payload shape, see Get run logs.

​
Run stuck in “queued” status

If a run stays in queued for more than a few minutes:
  1. Check your run status: arga runs status <run_id>
  2. Inspect the current logs snapshot: arga runs logs <run_id> --errors-only
  3. Cancel and retry: arga runs cancel <run_id>, then start a new run
  4. If the issue persists, contact founders@argalabs.com

​
Plan limits

​
”Monthly free plan limit reached.”

Free plan users get 10 validation runs per month. Limits reset on a rolling monthly basis. Check your remaining usage with: 
arga whoami
To get more runs, upgrade to the Team plan.

​
”Free plan allows 1 twin per run.”

Free plan users can use one digital twin per validation run. To use multiple twins in a single run, upgrade to the Team plan.

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

PR validation (arga previews pr-checks run) and CI checks are Team plan features. Upgrade to enable automatic PR validation.

​
”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 runs 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, discord, notion, jira, github.

​
Twins expired during testing

Twin sessions have a default TTL of 10 minutes. 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”

You need to connect GitHub before using features that depend on repository access (PR validation, CI checks). Go to Integrations and click Connect on the GitHub card.

​
”GitHub reauthentication required”

Your GitHub OAuth token has expired or been revoked. Go to Integrations, disconnect GitHub, and reconnect it.

​
”GitHub integration required for validation.”

PR and branch validations require a connected GitHub integration. Connect GitHub from the Integrations page before running arga previews pr-checks run or setting up CI checks.

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

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