Help

Troubleshooting & FAQ

What each error means and how to fix it, plus answers about data handling and what leaves your repository.

Errors#

401 invalid_token#

{"error": "invalid_token", "detail": "missing bearer token"}

• "missing bearer token": no Authorization header arrived. Check the header name, the word Bearer and the space, and that your environment variable is set in the process that runs the client (GUI apps often do not see variables from your shell profile).
• "invalid or revoked access token": the PAT is wrong, cut short when copying, or revoked. Tokens are arpat_ plus exactly 43 characters. Create a new one.
• OAuth tokens: expired (they last 60 minutes), issued for another audience, or missing the …/mcp/invoke scope.

Thirty failed authentications from one IP within 5 minutes lock that IP out for the rest of the window, so fix the config before retrying in a loop.

403 insufficient_scope#

On tools/call: your role in the organisation does not allow that tool (for example a member calling pr_open, or a viewer calling fix_submit). The JSON-RPC error message names the scope and the role permission needed. On any request: you were removed from the token's organisation. Ask an owner or admin; your existing tokens pick up a new role immediately.

402 / quota_exhausted#

Your monthly allowance is used up. The web API answers HTTP 402; over MCP it is a tool result with isError: true. Both carry resets_at and options:

• request_more: in the app, "Request more uses" (one pending request at a time).
• wait: the allowance resets at 00:00 UTC on the 1st.
• upgrade: payments are not enabled yet, so this is not available today.

Uses held by jobs that end without a PR come back automatically. A reservation whose job never finished is released by the reaper within about an hour; a verified fix waiting for your approval holds its use for up to 7 days, so approve or reject waiting fixes to free it sooner.

429 rate_limited#

Per IP: 120 requests a minute. Per person (all your tokens together): 60 requests a minute. fix_submit plus pr_open: 10 an hour. Wait for Retry-After (HTTP) or retry_after_seconds (tool error). A model polling job_status in a tight loop is the usual cause; ask it to wait between checks.

scan_failed, or a fix job that fails at checkout#

The repository could not be cloned. The usual reasons:

• It is private. Fix jobs run in a build that has no GitHub token by design and only clone public repositories. Scans of private repositories work only for the one repository the deployment holds a token for.
• The owner/name is misspelled, or the repository was renamed or deleted.

The rest of a multi-project repos_affected call still succeeds; failed projects are listed under errors.

not_approved#

pr_open needs a verified job and an approved open_pr decision. Open the job in the app, read the evidence, click Approve PR, then retry. Jobs that ended failed, unverifiable or needs_approval cannot open a PR.

"Vulnerability data is stale" banner#

The advisory sources have not synced within 48 hours (or never). Arachne keeps serving the last good data rather than nothing, so results may miss very recent advisories. Automatic feed sync is not scheduled yet; the banner clears after the next successful sync.

My client can't connect#

1. Run the curl checks. If curl works, the problem is the client's config.
2. Make sure the URL is exactly https://arachne.withaadhi.com/mcp and the transport is HTTP / Streamable HTTP, not SSE or stdio.
3. Arachne does not offer an SSE stream on GET /mcp (it answers 405); clients should fall back to plain POST responses. A client that insists on SSE-only transport will not work.
4. Claude Desktop without request headers: use the mcp-remote bridge (needs Node.js), and run the same npx mcp-remote … command in a terminal to see errors the app hides.
5. Client tries to "sign in" and fails: it is attempting OAuth discovery. Configure the PAT header instead.

FAQ#

What leaves my repository?#

Arachne clones the repository (shallow, no git history kept) into a temporary directory to read manifests and, for a fix, to build and test it in the sandbox. What it stores: the project record (name, owner/name), the dependency inventory (ecosystem, package, version), findings, and each job's evidence (plan, gate results with short log tails, the diff of the dependency files it changed). The working copy is deleted when the scan or job finishes. Your source code is not sent to any language model: the fixer model is not enabled in production.

Does my AI assistant's model see my code?#

Only what Arachne's tools return: advisory data, findings (package names and versions), version proposals and job status. None of the tools return your source files.

Can Arachne open a PR without me?#

No. Every PR needs a verified job and a person's approval in the web app; no MCP tool can approve. Writes are further limited to an allowlisted repository and to remediation/… branches, never the default branch.

How do I remove my data?#

Revoke your MCP tokens from the dashboard at any time. There is no self-service account deletion in the app yet; ask the operator, who can run the deletion (the service finishes interrupted deletions on a schedule).

Do I pay for model usage?#

Arachne does not run a model in your conversation, so it does not bill for tokens. Your own model provider does, for whatever your assistant processes, including the tool results it reads.