Skip to main content

Troubleshooting

Start with the error shown by CatalEx and check:

catalex status
catalex providers
catalex install status

Use catalex COMMAND --help for the flags supported by your installed release. Fix the reported cause and repeat the same operation before creating another agent or account.

Setup does not start​

Check the component states in catalex status. If the required provider is missing, too old or signed out, install/update it or complete its login, then check providers again. catalex providers discover refreshes the installed inventory.

If a port is occupied, choose free ports using the flags listed in catalex setup --help. Repeating setup preserves saved choices. Do not delete the state directory as a first repair step.

The app will not open​

Check that the release includes the app for your platform and that it was installed. catalex open needs the installed launcher. A successfully configured service does not mean a desktop app was installed.

A native agent cannot start​

Read the provider’s error in the conversation. Check the registered folder, provider sign-in, project configuration and tool permissions. Fix the cause, then choose Start new session when offered.

If a provider updated itself, refresh the inventory and retry. Do not loosen the folder’s permission policy just to avoid a refusal.

A tool or instruction is missing​

Confirm the agent uses the intended folder and provider. Check the folder’s own instructions and MCP/tool setup. Ask a specific question requiring that tool after the fix. A generic self-description is not evidence that tool access works.

Messaging is connected but silent​

Check the full path:

  1. Is the messaging service running and publicly reachable?
  2. Is the right bot, number or app connected and assigned to the intended agent?
  3. Does its allowlist admit the sender, and does its blocklist refuse them?
  4. Can that agent answer in a native chat?
  5. Does the inbound conversation appear under the agent’s channel?
  6. Does an actual reply arrive in the original messaging app?

For local services, make sure the tunnel forwards to the messaging service address CatalEx shows. A tunnel to the control API or another local port cannot receive the correct callbacks.

For WhatsApp, also check Meta recipient verification, account permissions and sender registration. See the WhatsApp troubleshooting table.

Too many messages are waiting​

Let the current turn finish or stop it before sending more. A queue-full message means the input was refused; keep your draft and retry once space is available. Inspect history before resending an operation with external effects.

Reporting a problem​

Include the release version, operating system, command or screen, exact error code, and whether the same agent works in native chat. Describe whether a message reached the messaging app, Relay’s conversation history, or neither.

Remove access tokens, app secrets, private folder paths, personal phone numbers and message content that is not needed to reproduce the issue. Report through the Relay repository.