Skip to content

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.