Match the symptom below and follow its recovery rule. Do not retry terminal failures.
AgentGrid.io tools are missing
An MCP client may bind servers only at startup. Restart the session and verify with workspace-list_artifacts. If tools remain absent, confirm this configuration:
{ "mcpServers": { "anima": { "type": "http", "url": "https://api.agentgrid.io/v1/mcp" } } }
The CLI requires no MCP setup and is a fallback.
Artifacts land in the wrong team
This is expected when consent targeted another team. The token is pinned to its approved team; tools have no team parameter. Re-authorize the Claude connector or ChatGPT plug-in, or run login against the correct team. Artifacts cannot move between teams; duplicate them or export and re-import.
Git fails with DNS, proxy, or firewall errors
Do not retry: the environment has no route to the git remote. Use artifact-explore and artifact-edit; they commit to the same repository without the agent's network. A token-expired error is different and may be retried after minting a fresh remote.
Device or polling failures
- Device code stopped working: codes last about 15 minutes. Run
loginagain. authorization_pending: nobody has claimed yet; keep polling.expired_token: either the human claimed without agent access or the 24-hour claim window closed. This is terminal. Ask the human to claim a fresh artifact and grant access or create an agent invite.slow_down: increase polling interval; about every 30 seconds is appropriate.
Refresh failures
For 400 invalid_grant, stop retrying. Unknown, expired, revoked, and reused tokens return the same answer; do not infer which occurred. Discard the stored pair and reconnect through a fresh claim for the fast path or npx @animaapp/cli@latest login.
If a refresh call never completed, retry immediately with the same token because a short grace period covers a lost response. Do not save it for later: an old refresh token resurfacing is treated as compromised and retires the credential.
Expired git token
Git tokens last at most one hour and cannot be renewed. Mint a new remote:
npx @animaapp/cli@latest get-git-token <sessionId>
git remote set-url origin <gitRemoteUrl>
Terminal authorization and quota errors
403 agent_revoked: do not retry. Tell the human access was revoked and that they can re-invite through Share → Invite an agent.402 quota_exceeded: do not retry. Relay the full message, including the error body's upgrade link, and stop creating artifacts until the condition clears.
Artifact renders blank
The artifact is an app without index.html, commonly because markdown was sent with the wrong type. Create a new document. See Artifact types.
Verify or disconnect
npx @animaapp/cli@latest list returning artifacts confirms connection. A human can also inspect Share → Manage access. If a connected agent sees nothing, it may target another team or have read on an empty scope.
logout clears local credentials and configuration only; it does not revoke the identity.