Troubleshoot connectors
The error codes a connector can return, what they mean, and how to fix the common problems with sign-in, approvals, limits, destinations and packages.
Enterprise module
Connectors are an enterprise module. A request without an active Enterprise licence, or with the Connectors or Tools service switched off, is refused with 402. See Connector security and limits.
Find the code or the message you see in the tables, then use the section for your situation.
Errors from a connector call
A connector action that fails returns one of these codes to the agent, with a message and sometimes a hint and a wait time. The message never holds a secret.
| Code | What it means | What to do |
|---|---|---|
AUTH_FAILED | The system refused the credential: wrong or expired token, key or password. | Connect the account again on the connector. For a database or mail server, check the user name and password. |
FORBIDDEN | The credential is valid but may not do this. | Give the account the permission the system needs, or use an account that has it. For SQL, check the database user's grants. |
NOT_FOUND | The thing asked for does not exist, or the account cannot see it. | Check the name, id or path, and that the account can read it. |
INVALID_INPUT | The request is not valid: a missing field, a value outside its range, a result larger than Console reads. | Read the message and hint. Send fewer rows or columns, or a shorter value. |
CONFLICT | The request clashes with the current state. For mail: the same message was sent lately. | Wait before sending the same message again. After a failure past the mail server's data step the hint says The server may have accepted the message; check the Sent items before sending again. |
RATE_LIMITED | A limit was reached: the vendor's, or one of Console's limits. | Wait the time in the message (retryAfterSec) and try again. See Rate limited. |
UPSTREAM | The system could not be reached, answered with an error, or did not answer as expected. On SaaS, network detail is left out of SQL and mail messages. | Check the server address and the system's status, then try again. For a database or mail server also check TLS settings and the port. |
TIMEOUT | The call did not finish in time. | Narrow the request. For SQL, lower the rows or simplify the statement. See the timeouts. |
EGRESS_DENIED | The address is not one a connector may reach. | See A destination is refused. |
POLICY_DENIED | The request breaks a rule: a write through a read-only call, a request shape the package may not send, or a file that was not asked for. | Use a tool that is meant for this. If it keeps happening, the package may need an update. |
RUNTIME_UNAVAILABLE | The package process could not run. | Try again. If it stays, ask the operator to check the Console logs. Package code can be switched off on a server (CONNECTOR_RUNTIME_MODE=off). |
Errors from the dashboard and the API
The connector service answers in English with a code. The common ones:
| Code | What it means | What to do |
|---|---|---|
VALIDATION_ERROR | A value is missing or malformed. The error names the field. | Fix the field. A key uses lowercase letters, digits and dashes (up to 40 characters, starting with a letter or digit). A name has at most 120 characters. |
invalid_config | The settings do not work: a required setting is missing, or the package offers no tools with them. | Open the connector's Settings tab and check the named setting. |
NOT_FOUND | The connector was not found. It may be in another project. | Switch to the project that holds it. |
FORBIDDEN | Only a tenant owner or admin may do this, for example manage OAuth apps. | Ask an admin. |
duplicate_key | A connector with this key exists in the project. | Choose another key. |
unknown_definition | The connector package is not installed. | Install it again. See Install packages. |
invalid_method | The sign-in method is not available with these settings. | Choose another method, or change the settings. |
account_required | The connector has no connected account, or its sign-in no longer works. | Connect the account first, or connect it again. |
oauth_app_missing | No OAuth app is set up for this sign-in. | A tenant admin adds one under OAuth apps. |
oauth_state_invalid | The sign-in link is not valid any more. | Start the sign-in again from the project where you began it. |
oauth_failed | The vendor did not complete the sign-in, or you canceled it. | Start again. |
credential_rejected | The system refused the credential. | Check the key or token and its permissions. |
credential_unavailable | The stored credential cannot be read. | Connect the account again. |
vendor_unavailable | The system could not be reached or did not answer in time. | Try again. |
connector_unavailable | The package could not run. | Try again; ask the operator if it stays. |
connector_policy | The package tried to reach an address that is not allowed. | See A destination is refused. |
not_active | The connector is disabled. | Select Enable connector. |
sync_running | A sync of this source is already running. | Wait, or select Cancel run. |
invalid_target | The Knowledge Engine module was not found in this project or is not active. | Choose an active module of the project. |
invalid_source | The package does not offer this source. | Check the connector's settings and package version. |
invalid_schedule | The schedule is not one of the presets, or is shorter than the source allows. | Choose a longer schedule. |
acl_ack_required | You did not confirm that everyone with access to the module sees every document. | Tick the confirmation on the source form. |
target_locked | The module of a source cannot be changed. | Delete the source and add it again. |
not_held | Only the latest run of a source can be confirmed, and only while it is held. | Open the source and use the buttons on its latest run. |
Sign-in fails
Connecting an account with a key, token or form checks the value before it is kept.
- Enter the full value, not the hint that is shown. The field holds the
…1234hint of a stored secret. Paste the whole value again. - The system refused access (
credential_rejected): the key, token or password is wrong or lacks permission. - {vendor} sign-in needs the server settings first: fill in the connector's settings, such as the server address, and connect again.
- A warning on the connector says why the account needs attention: The server address changed. Connect the account again., The connected account uses a sign-in method these settings no longer allow. Connect it again., or The stored credential cannot be read. Connect the account again. Connect the account again in each case.
OAuth return fails
After sign-in at the vendor, Console shows The sign-in did not work with one of these:
| Message | What to do |
|---|---|
| The sign-in link is not valid any more, or it was started by someone else or in another project. Start the sign-in again. | The link lasts 10 minutes and works only in the project and for the person who started it. Start again. |
| The vendor did not complete the sign-in, or you cancelled it. Start again. | Start again and approve the access. |
| No OAuth app is set up for this sign-in. A tenant admin can add one under OAuth apps. | A tenant owner or admin registers the app under OAuth apps. |
| The system refused the credential it got. | Check the OAuth app's client id and secret. |
| Start the sign-in again. If it keeps failing, a tenant admin can check the OAuth app under OAuth apps. | An unknown code. Start again, then check the app. |
A tool asks for approval in an unattended run
A connector only marks its actions as read, write or destructive. Read tools run. Every other tool asks for approval by default, and a run with nobody to answer cannot approve it. By default the tool then does not run, and the agent is told that it needs human approval and that no approver is available.
To let a tool run unattended, the agent's owner sets that tool to Never ask in the agent's Approvals & questions, or chooses what happens when nobody can answer. See Tool approvals and questions and which tools ask. The connector itself has no approval setting. To see which actions are write or destructive, open the connector's Tools tab.
Rate limited
RATE_LIMITED comes from the vendor or from a Console limit. The result carries the seconds to wait.
- Mail: 10 sends a minute and 60 an hour per connector, 30 and 300 for the tenant. Also at most 2 mail sessions at once per connector.
- SQL: at most 4 statements at once per connector, and 6 failed connection attempts a minute.
- Sync: if the vendor asks Console to wait more than 60 seconds, the run ends Partly done and the next run continues.
Wait and retry, spread calls over time, or reduce how often a schedule runs. The full list is in Limits and timeouts.
A destination is refused
EGRESS_DENIED or connector_policy means a connection was refused before it was made. Check, in order:
- Address. A server you enter must be a real host name or public IP. Loopback, link-local and metadata addresses are refused everywhere.
- Private network. A private address (10.x, 172.16-31.x, 192.168.x and similar) is refused on SaaS. On-prem it works only when the package supports a private network. If the operator has set
CONNECTOR_EGRESS_PRIVATE_CIDRS, the address must be inside it. - Scheme and port.
httpson port 443, or the port you entered. Plainhttpis accepted on-prem only. On SaaS some ports are refused for object storage servers. - Name. A name that resolves to several addresses is refused when any of them is refused.
- TLS mode. The SQL TLS modes Encrypted, check nothing and Not encrypted are on-prem only.
When the name does not resolve, the call returns UPSTREAM and the server could not be reached. Check the spelling and DNS. See Where calls may go.
A package does not install or its signature fails
Console accepts only signed .cpkg packages and checks the signature before it installs one. A package that fails is skipped, and the Console log shows the reason (Connector package skipped).
| Reason | Meaning |
|---|---|
bad_signature | The signature is missing, not valid, does not cover these files, or names another package or publisher. Download the package again from its release. Do not edit its files. |
bad_checksums | The checksum list is damaged. Download again. |
bad_index | The package index is not valid or lists no packages. |
too_large, too_many_entries | The package is over a limit: 50 MB, 100 MB unpacked, or 2000 files. |
If No connector types are installed shows in the picker, install a package from the catalog first. A connector whose package is gone shows The connector package is not installed and only deleting it works. See Install packages.
A sync shows no tools
On the connector's Tools tab:
| What you see | What to do |
|---|---|
| Tools are not synced yet | Select Sync tools to create the tool in Tools. |
| Connect an account first | Tools are listed with the connector's account. Connect it. |
| Connect the account again first | The sign-in no longer works. Connect again. |
| No tools with these settings | This connector offers no tools with its current settings or sign-in method. Change the settings or the sign-in method. |
| The connector is disabled | The tool stays off while the connector is disabled. Select Enable connector. |
| The tool is turned off | Select Sync tools to turn it on again. |
| Could not sync tools | Read the message under it, fix the settings, and try again. |
An action is on while the current settings allow it, so a setting can switch actions off. A connector that uses the vendor's MCP server shows This connector uses the vendor's MCP server now, so its own actions are off.
A knowledge source does not run
Open the Knowledge tab. A source in Paused state shows its reason (module missing, not active or re-indexing, account needs attention, connector disabled, package not installed). A run in Held state waits for an admin. See Connector knowledge sources.