Troubleshooting Connectors
When a Connector needs attention, its card on the Connectors page will say what is wrong. Start there, then use the tables on this page to find what to do.
Where this page says Configure → Credentials, a Connector built or imported on this Gateway uses the editor's Auth tab instead: click Open in editor on its card.
Optima Connectors
This section covers Connectors installed from the marketplace, imported, or built on this Gateway.
Warnings On A Connector's Card
| Card says | What it means | What to do |
|---|---|---|
| Needs credentials | A credential the Connector signs in with is blank. Its tools fail until it is filled in | Configure → Credentials, enter it and Save. See Adding its credentials |
| Not connected | An OAuth sign-in is missing or has stopped working | Configure → Credentials, click Connect and sign in |
| Re-enter credentials | The Gateway can no longer decrypt a stored credential — usually because its database was moved or restored without its configuration file | Enter the credential again. Nothing can recover the old one |
| Auth incomplete | The Connector was published with a required sign-in value blank, which only its author can set | Contact the publisher, or install an updated version |
| Auth unsupported | The Connector uses a kind of sign-in this version of Optima cannot store yet | Update Optima, or contact the publisher |
| Needs runtime ≥ | The Connector needs a newer Python runtime than the Gateway has | Click it and update the runtime. See Setting Up the Gateway |
| Deps pending | Its Python packages are not installed yet, so its tools are hidden | Click it and Install now. See Python packages |
| Deps failed | Installing its packages failed | Click it to see the error, then Retry |
| disabled | The Connector is switched off | Switch it on. See Switching a connector off |
| Update available | A newer version is on the marketplace | Click it to update. See Updating |
Other Problems
| Problem | What to do |
|---|---|
| Python runtime is not ready — connectors cannot run. at the top of the page | Install the runtime. See Setting Up the Gateway |
| The Connector's tools never appear in chat | Check it is switched on, its packages are installed and nothing on its card needs attention. If people chat through an Assistant, check the Assistant has it ticked on its Tools tab |
| A tool says it timed out | The tool took longer than its timeout. See Timeouts |
| A tool returns an error from the other service, such as 401 or 403 | The key is wrong or lacks a permission the tool needs. The Connector's page in the Connector Catalogue lists what it needs |
| Connect does nothing, or the sign-in window never appears | Your browser blocked the popup. Allow popups for the Gateway, or click Open the sign-in page. See While you sign in |
| The callback URL is missing on the Credentials tab | Set Public address of this gateway in Settings |
| A Connector cannot be installed: Not included in licence | Enforce connector tiers is on and your licence does not include Professional connectors. See Community, Mixed and Professional |
| Marketplace unavailable | The Gateway cannot reach the marketplace. It needs internet access on port 443. Installed Connectors keep working |
| The Connectors page is not in the menu | You need the Optima Connectors or MCP Connectors permission |
MCP Connectors
An MCP Connector's card shows its state. The following states need attention:
| Card says | What to do |
|---|---|
| Unreachable | Check the address, and that the Gateway can reach the server. Open the Connector and click Try it now |
| Sign-in needed | Open the Connector's Sign-in tab and click Connect. See One organisation account |
| Credential refused | The server rejected the token or headers. Enter a new one on the Sign-in tab |
| Credential unreadable | The Gateway cannot decrypt the stored credential. Enter it again on the Sign-in tab |
| Certificate not trusted | Check the certificate with whoever runs the server, then trust it. See Certificates |
| MCP is switched off | Turn on Allow MCP connectors in Settings → AI |
| Off | Turn on Offer its tools in chat or Offer its tools to API callers on the Details tab |
Other problems with MCP Connectors:
| Problem | What to do |
|---|---|
| Someone does not get an MCP Connector's tools | If it has a shared credential, add them on its Access tab. If each person signs in, they need to connect their account, on Connected accounts. Also check the tools are switched on, on its Tools tab |
| A tool that used to work has disappeared | The server may have renamed or removed it. Click Refresh on the Tools tab. If Keep tools this server adds later switched off is on, a renamed tool arrives switched off |
| An OAuth sign-in fails behind a proxy server | OAuth sign-ins and calls go directly to the service, never through a proxy. Allow the Gateway direct access to it |
| Signing in fails with "needs an app registration" | Register an app at the service yourself. See When a service needs an app registration |
Still Stuck
If none of the above helps, turn on system tracing and look at the Gateway's log. See Diagnostics.