Board Tool troubleshooting

Sign-in did not return to the client

Restart the connection from the client and complete sign-in in the same browser session. If Budgee says the consent request expired, restart from the client; authorization requests and codes are intentionally short-lived.

Client developers should verify that the registered and returned redirect_uri match exactly, preserve state, use S256 PKCE with the original verifier, and send the same MCP resource through authorization and token exchange. Do not reuse an authorization code.

You cannot select or approve a board

No board is selected automatically. Choose at least one currently accessible board and check the external-data consent box. When a client requests write access, only boards where you are currently an owner or editor are offered.

If no boards appear, confirm that you signed in with the same Budgee account and that your role is current.

The client says permission denied

1. Was this exact board selected for the connection?
2. Did the connection request the needed scope? Read-only defaults exclude write, preview:apply, and imports:update.
3. Does the user still have the required role? Every operation rechecks it.

A rollout denial is not fixed by refreshing a token. Ask Budgee whether that environment and surface are enabled.

The connection expired or was revoked

Normal MCP clients should refresh automatically. A changed, revoked, or disconnected durable connection invalidates both current access and refresh tokens. Refresh-token replay also disconnects the connection.

Open User settings → AI connections. If the service is absent, reconnect and select boards and permissions again. For direct API credentials, rotate or recreate the credential, exchange it for a new access token, and update the secret store.

Board evidence is stale or catching up

Inspect budgee.get_read_model_status in MCP or readModel.status and structured HTTP error details. Wait for the authorized catch-up path, then repeat the read. Narrow an overly broad date range if the error is a bounded-cost limit.

Do not substitute an older result, browser state, or memory. If a transaction cursor became stale after a read-model generation change, restart the same query from page one without the cursor.

The preview changed or expired

A preview normally lasts 15 minutes, but relevant board or source-document changes can invalidate it sooner. Create a fresh preview from current facts, review its full impact, and obtain explicit approval again. Do not edit the old preview or reuse its approval.

An apply timed out

A transport timeout does not prove failure. If no structured result arrived, retry only the exact same preview and request with the same idempotency key. If you have a runId, poll the returned status operation.

For outcome-unknown or applied-unverified, inspect status, audit, and current board evidence before another apply. Never create a new idempotency key because the response was lost.

Disconnect and reconnect

1. Open User settings in Budgee.
2. Under AI connections, select Disconnect for the service.
3. Remove the stale Budgee entry from the external client if it remains.
4. Add the exact Budgee MCP URL again.
5. Sign in, select boards, review scopes, check consent, and approve.

Disconnecting invalidates external access immediately. It does not turn off Budgee's built-in Ask Budgee AI feature.

Information to keep for support

Keep the environment name, client name and version, time, operation or tool name, HTTP status, safe error codes, and requestId. Never send API keys, access tokens, refresh tokens, client secrets, private board identifiers, or customer transaction data unless Budgee provides an approved secure channel.