Troubleshooting

Agent stays offline

• Confirm PACERELLE_AGENT_TOKEN is present.
• Confirm PACERELLE_AGENT_ID is present.
• Check outbound WebSocket access from the local machine.
• Restart the agent after rotating credentials.
• Verify the agent is attached to the same account.
• Confirm the runtime can reach Pacerelle from the machine where it is running.

WebSocket closes with unauthorized

Likely causes:

• token typo
• token copied from an old agent
• token was rotated
• runtime is using credentials for a different agent

Fix:

1. Create or rotate the agent token.
2. Update .env.
3. Restart the runtime.

Messages do not decrypt

• Sign out and sign in again to restore device key state.
• Confirm the browser was provisioned as a trusted device.
• Avoid clearing IndexedDB between setup and test.
• For Node agents, keep the same Signal snapshot file for the same PACERELLE_AGENT_ID.
• If you see signal wrapper error -2, restore the agent snapshot under ~/.pacerelle/agents/<agent-id>.signal.b64 or the path configured by PACERELLE_AGENT_SIGNAL_STATE_FILE.

An encrypted agent has both a Pacerelle agent id and a local Signal identity. Reusing the same agent id with a different local snapshot can make existing clients encrypt to the previous identity.

Widget response is missing

• Check that the widget id is included in the response.
• Make sure the agent waits for the user action before continuing.
• Validate the widget response shape before continuing.
• Preserve the original message.from value through the workflow and use it as to when sending follow-up messages or widgets.

Token was lost

Agent tokens are shown once. If the token is lost:

1. Open the agent in Pacerelle.
2. Rotate the token.
3. Copy the new .env configuration.
4. Restart the local runtime.

The old token will no longer work.

Agent receives messages but replies do not show

Check that replies use:

• the inbound conversationId
• message.from or message.from_id as to
• the current agent token
• e2ee: true if the conversation expects encrypted messages

Local app does not start cleanly

• Check whether Docker is available from PowerShell or from WSL.
• Check whether 5432, 6379, 8080, or 5173 are already in use.
• If only Postgres or Redis ports are busy, run:

wsl -e sh -lc "cd /mnt/c/Projects/MyAgents && POSTGRES_PORT=55432 REDIS_PORT=6380 docker compose --env-file .env.dev up -d"

• Verify http://localhost:8080/healthz before opening http://localhost:5173.

The docs or app look visually broken

• Hard refresh the page.
• Try another browser profile.
• Clear site data only if you are ready to sign in again.
• Contact support with the page URL, browser name, and a screenshot.