Troubleshooting

The agent stays offline

• Make sure the program is still running and didn't exit with an error.
• Check that .env contains both PACERELLE_AGENT_ID and PACERELLE_AGENT_TOKEN, and that they belong to the same agent.
• Restart the program after editing .env. With Node, run it with node --env-file=.env.
• Check that the machine can reach https://api.pacerelle.com (outbound HTTPS and WebSocket). Corporate proxies sometimes block WebSockets.

The connection is refused (unauthorized)

The token is missing, mistyped, from another agent, or was replaced. Replace the token, update .env and restart.

Messages don't reach the handler

• Check that the agent is online in the app.
• In a group, check the agent is a member. A mention doesn't add it, and it only receives messages sent after it joined.
• Make sure you registered the handler with onMessage (on_message) before calling connect().
• Only one program should run per agent. A second instance competes for the same messages.

The agent receives messages but replies don't appear

• Reply with the incoming message's conversation and sender — the simplest way is agent.reply(message, …) in JavaScript.
• Keep e2ee: true (e2ee=True). Unencrypted replies are for local debugging only.
• Make sure the handler doesn't throw before sending. Log errors with onError.

Messages can't be decrypted after a restart

The agent's encryption identity lives in its state file. If it was deleted, moved or replaced, the agent comes back with new keys and older sessions can't be decrypted.

• Restore the original state file — see locations.
• Never share a state file between two running programs, or between two agents.
• If the state is lost for good, the cleanest fix is to create a new agent, point your program at it, and delete the old one.

WebSocket is unavailable in this runtime (JavaScript)

Import the Node entry point: createNodeAgentGatewayClient from @pacerelle/sdk/node.

pip can't find a matching distribution (Python)

The alpha wheels target CPython 3.12 on Windows x64/ARM64, Linux x64/ARM64 and macOS ARM64. Use Python 3.12 and install with the pre-release flag: pip install --pre pacerelle.

A widget answer never comes back

• The user may not have answered yet — widgets wait for them.
• Check the widget hasn't expired (expiresAt).
• Match answers on widgetResponse.ref, and handle cancelled.

The MCP assistant doesn't answer

• The host must keep a session calling wait_for_messages. Start it with the start_pacerelle prompt and keep the session open.
• Only one host can use the agent at a time on a machine: close the server in the other host.
• See MCP hosts.

Still stuck?

Note the agent name, the time of the issue, your SDK version and the error printed by your program (without the token), and write to support@pacerelle.com.