# Connections diagnostics

<!-- Generated by docs/modules/diagnostics from the package catalogs. Write a guide in docs/diagnostics/<CODE>.md instead of editing this file. -->

Each Connections error has a stable `code`. Its `docs` link opens the page of that code. This page lists all 44 codes, and [All diagnostics](https://vitehub.dev/docs/reference/diagnostics) lists every primitive.

## Runtime errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_APPROVAL_REQUIRED`](https://vitehub.dev/docs/connections/diagnostics/connections_approval_required) | Approval is required for \<action\> on Connection "\<connection\>". Request: \<approval\>. |
| [`CONNECTIONS_DENIED`](https://vitehub.dev/docs/connections/diagnostics/connections_denied) | Actor "\<actor\>" may not call \<action\> on Connection "\<connection\>". |
| [`CONNECTIONS_INVALID_INPUT`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_input) | Method "\<method\>" requires "\<parameter\>". |
| [`CONNECTIONS_NEEDS_RECONNECT`](https://vitehub.dev/docs/connections/diagnostics/connections_needs_reconnect) | Connection "\<connection\>" must be connected again. \<connection\> |
| [`CONNECTIONS_NOT_CONNECTED`](https://vitehub.dev/docs/connections/diagnostics/connections_not_connected) | Connection "\<connection\>" uses an API key. Set it with `vitehub connections set-key <connection>`. |
| [`CONNECTIONS_ORIGIN_NOT_ALLOWED`](https://vitehub.dev/docs/connections/diagnostics/connections_origin_not_allowed) | Connection "\<connection\>" does not send its token to \<origin\>. |
| [`CONNECTIONS_PROVIDER_FAILED`](https://vitehub.dev/docs/connections/diagnostics/connections_provider_failed) | Provider "\<provider\>" rejected the token request\<value\>\<value\>. |
| [`CONNECTIONS_UNAVAILABLE`](https://vitehub.dev/docs/connections/diagnostics/connections_unavailable) | Connection "\<connection\>" has a token mutation in progress. Try again. |

## Configuration errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_INVALID_ACTOR`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_actor) | This Connections runtime method records who made the decision, so it requires `actor`. It has no default. |
| [`CONNECTIONS_INVALID_CONFIG`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_config) | Connections activityRetention.\<name\> must be a positive integer, or set activityRetention to false to keep all activity. |
| [`CONNECTIONS_INVALID_DEFINITION`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_definition) | The authorization server of Connection "\<connection\>" does not offer client registration. Set the provider `clientId`. |
| [`CONNECTIONS_INVALID_NAME`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_name) | Connection name "\<name\>" from "\<file\>" exceeds 501 characters, so its Env keys do not fit the 512-character limit. |
| [`CONNECTIONS_INVALID_PROVIDER`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_provider) | The API key provider origin \<origin\> contains a wildcard. ViteHub sends the key only to exact origins. |
| [`CONNECTIONS_INVALID_STORED_DATA`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_stored_data) | Stored token for Connection "\<connection\>" is invalid. |
| [`CONNECTIONS_NOT_CONFIGURED`](https://vitehub.dev/docs/connections/diagnostics/connections_not_configured) | Connections need VITEHUB_CONNECTIONS_KEY, or VITEHUB_CONNECTIONS_KEYS as a comma list with the current key first. Each key is 32 random bytes as base64 or hex. Create one with `openssl rand -base64 32`. |
| [`CONNECTIONS_NOT_FOUND`](https://vitehub.dev/docs/connections/diagnostics/connections_not_found) | No Connection Definition was discovered for "\<connection\>". |
| [`CONNECTIONS_UNKNOWN_ACTION`](https://vitehub.dev/docs/connections/diagnostics/connections_unknown_action) | Connection "\<connection\>" does not expose \<action\>. |

## Management route errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_AUTH_REQUIRED`](https://vitehub.dev/docs/connections/diagnostics/connections_auth_required) | Connections management requires an actor module outside local development. |
| [`CONNECTIONS_AUTHORIZATION_CANCELLED`](https://vitehub.dev/docs/connections/diagnostics/connections_authorization_cancelled) | The provider did not grant access. |
| [`CONNECTIONS_AUTHORIZATION_EXPIRED`](https://vitehub.dev/docs/connections/diagnostics/connections_authorization_expired) | The authorization link expired or was already used. Each link works one time, for 10 minutes. |
| [`CONNECTIONS_CONTENT_TYPE_REJECTED`](https://vitehub.dev/docs/connections/diagnostics/connections_content_type_rejected) | Connections management accepts only application/json requests. |
| [`CONNECTIONS_FORBIDDEN`](https://vitehub.dev/docs/connections/diagnostics/connections_forbidden) | Another user started this authorization request. Start the connection again. |
| [`CONNECTIONS_INVALID_REQUEST`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_request) | Connection "\<connection\>" uses OAuth. Connect it with `vitehub connections connect <value>`. |
| [`CONNECTIONS_METHOD_NOT_ALLOWED`](https://vitehub.dev/docs/connections/diagnostics/connections_method_not_allowed) | Use \<method\>. |
| [`CONNECTIONS_ORIGIN_REJECTED`](https://vitehub.dev/docs/connections/diagnostics/connections_origin_rejected) | The browser origin does not match the origin that the server sees. |
| [`CONNECTIONS_REQUEST_FAILED`](https://vitehub.dev/docs/connections/diagnostics/connections_request_failed) | The Connections request failed. |
| [`CONNECTIONS_ROUTE_NOT_FOUND`](https://vitehub.dev/docs/connections/diagnostics/connections_route_not_found) | Not found. |
| [`CONNECTIONS_STATE_CONFLICT`](https://vitehub.dev/docs/connections/diagnostics/connections_state_conflict) | Connection "\<connection\>" belongs to another account. Confirm the provider outcome and repair the mutation lease before revoking or connecting again. |
| [`CONNECTIONS_STATE_MISMATCH`](https://vitehub.dev/docs/connections/diagnostics/connections_state_mismatch) | The callback has no `state` cookie of this browser, or the cookie does not match. |

## Errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_CHATGPT_CLIENT`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_client) | ChatGPT plan grants can be used only through the ChatGPT Agent gateway. |
| [`CONNECTIONS_CHATGPT_IDENTITY`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_identity) | The ChatGPT ID token did not pass identity validation. The new credentials were not accepted. |
| [`CONNECTIONS_CHATGPT_LOOPBACK`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_loopback) | ChatGPT plan usage requires an HTTP callback on 127.0.0.1. Website redirects grant identity only. |
| [`CONNECTIONS_CHATGPT_PERMISSION`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_permission) | The ChatGPT grant does not include permission to use the plan. |
| [`CONNECTIONS_CHATGPT_REGISTRATION`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_registration) | The ChatGPT callback did not match the pending client registration. |
| [`CONNECTIONS_CHATGPT_TRANSFER`](https://vitehub.dev/docs/connections/diagnostics/connections_chatgpt_transfer) | The ChatGPT credential file is invalid, or the destination already has another active grant. |

## CLI errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_CLI_ARGUMENTS_INVALID`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_arguments_invalid) | See the page of the code. |
| [`CONNECTIONS_CLI_CALLBACK_FAILED`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_callback_failed) | See the page of the code. |
| [`CONNECTIONS_CLI_CREDENTIAL_FILE_INVALID`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_credential_file_invalid) | See the page of the code. |
| [`CONNECTIONS_CLI_REQUEST_FAILED`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_request_failed) | See the page of the code. |
| [`CONNECTIONS_CLI_SERVER_UNREACHABLE`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_server_unreachable) | See the page of the code. |
| [`CONNECTIONS_CLI_TRANSPORT_INSECURE`](https://vitehub.dev/docs/connections/diagnostics/connections_cli_transport_insecure) | See the page of the code. |

## Approval errors

| Code | What happened |
| --- | --- |
| [`CONNECTIONS_EXECUTION_UNKNOWN`](https://vitehub.dev/docs/connections/diagnostics/connections_execution_unknown) | The provider may have completed this write. Check the provider before requesting another approval. Approval: \<approval\>. |
| [`CONNECTIONS_INVALID_APPROVAL`](https://vitehub.dev/docs/connections/diagnostics/connections_invalid_approval) | Approval belongs to a previous Connection grant. |
| [`CONNECTIONS_KEY_REJECTED`](https://vitehub.dev/docs/connections/diagnostics/connections_key_rejected) | Provider "\<provider\>" rejected the key. |

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/connections.md)
- [Get started](https://vitehub.dev/raw/docs/connections/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/connections/configure.md)
- [Server API](https://vitehub.dev/raw/docs/connections/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/connections/limits-and-errors.md)
- [ChatGPT plan usage](https://vitehub.dev/raw/docs/connections/chatgpt.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
