Troubleshooting

CLI and MCP Auth

Symptom: login polling never authorizes

What to check:

• Ensure you approved the exact device code in the browser approval flow.
• Confirm CLI/MCP is targeting the same control plane URL shown in the browser.
• Wait for poll interval and avoid excessive polling to prevent slow_down.

Recovery:

1. Run login again to generate a fresh device code.
2. Approve the new user code in the web app.
3. Poll again with the new deviceCode.

Symptom: 401 on authenticated commands

What to check:

• Local auth store may be missing, expired, or tied to another control plane URL.

Recovery:

1. Run roberto auth refresh.
2. If refresh fails, run roberto auth logout --local-only.
3. Run roberto auth login again.

Runtime Update Flow

Symptom: runtime apply fails with approval or grant errors

What to check:

• approved=true is required for apply calls.
• Grant token must match runtime/agent/channel/target version and must be unexpired.

Recovery:

1. Re-check update state (runtime-check-updates or agent update status).
2. Issue a fresh grant token.
3. Re-run apply with --approve --grant-token <token>.

Symptom: script download fails during apply

What to check:

• Runtime access token validity.
• Script URL must come from the control plane update decision payload.

Recovery:

1. Refresh runtime auth token.
2. Re-run check to get current script URLs.
3. Re-run apply.

Billing and Entitlements

Symptom: cannot provision/start or gateway returns billing-related rejection

What to check:

• Current entitlement flags and subscription status.
• Credits/subscription state may be out of sync after billing changes.

Recovery:

1. Run roberto billing status and roberto billing summary.
2. Run roberto billing sync.
3. If provisioning remains blocked, run roberto billing setup or open billing portal.

Symptom: checkout or portal session creation fails

What to check:

• Confirm you are authenticated (roberto auth whoami).
• Check current billing readiness (roberto billing status).
• If you do not have an active subscription/customer yet, use roberto billing setup.

Recovery:

1. Re-run with roberto billing checkout, roberto billing credits-checkout, or roberto billing portal to capture exact API error payload.
2. Retry from the web settings billing page.
3. If the error persists, contact your workspace admin/support with timestamp + command output.

Gateway Access

Symptom: 401 from /api/gateway/*

What to check:

• Gateway token must be provided via Authorization or x-api-key.
• Token must belong to the target agent.

Recovery:

1. Re-fetch gateway credentials for the agent.
2. Retry request with the new credential.

Symptom: 503 from managed gateway

What to check:

• Managed provider may be temporarily unavailable.

Recovery:

1. Retry request after a short delay.
2. If persistent, contact your workspace admin/support with request timestamp.

Usage Webhooks

Symptom: webhook requests rejected

What to check:

• agentId query parameter is required.
• JSON body must be valid and include numeric usage fields.
• Signature header may be mandatory depending on deployment config.

Recovery:

1. Include valid agentId.
2. Sign payload with expected secret and set x-roberto-signature when enabled.
3. Use x-idempotency-key to safely retry delivery.