Troubleshooting

Symptoms, causes, and fixes for the common failures.

Start from the CLI exit code and error.code, then find the row here. The full list is in the error catalog.

503 server_misconfigured

The Worker refuses to serve before authenticating or contacting Slack.

• Cause: one of NOTIFY_API_KEY, SLACK_BOT_TOKEN, SLACK_TARGETS is missing or malformed. The key must be 32 to 256 printable ASCII characters; the token must match xoxb- plus alphanumerics and dashes; the targets must be a non-empty JSON object (at most 100 entries) of valid aliases to channel IDs, in at most 16 KiB.

• Fix: run pnpm ops:push-secrets --dry-run, correct worker.env, then push. It is expected before Slack is wired.

• Not a bug if SLACK_WIRED is not true; the smoke test accepts it.

401 unauthorized

The relay key does not match. Compare ZUDO_SLACK_NOTIFY_API_KEY in sender.env with NOTIFY_API_KEY in worker.env, and re-push if you rotated. Watch for trailing whitespace or quotes in the env file.

slack_rejected with not_in_channel

The bot is not a member of the destination. Run /invite @zudo-slack-notify in the channel. Also check the ID: a wrong or archived channel yields channel_not_found or is_archived.

slack_rejected with invalid_auth, token_revoked, token_expired

The bot token in the Worker is stale. Rotate the Slack token.

403 target_not_allowed

The alias is not in SLACK_TARGETS. Check spelling; aliases are lowercase kebab-case. Update the secret and push.

Delivery unknown (exit 4)

slack_timeout, slack_network_error, slack_delivery_unknown, slack_invalid_response, client_timeout, client_network_error, or unrecognized_response.

Open the Slack channel and look. If the message is there, the send succeeded and nothing more is needed. If it is not, resend deliberately. Do not script an automatic retry; see Delivery semantics. Use the requestId from the output to find the request in Worker logs (observability is enabled).

Rate limits (429, exit 3)

Slack throttled the post. Wait at least Retry-After (also in retryAfterSeconds) before sending again, and reduce how often the caller sends. Threaded replies and a single summary message help.

400 invalid_request or rendered_message_too_long

The message names the offending field. rendered_message_too_long means escaping pushed text over a Slack limit; shorten it. Run the same input with --dry-run to reproduce locally without the network.

CLI exit 2

An input or configuration problem, printed on stderr as local_input_error: a missing or non-HTTPS ZUDO_SLACK_NOTIFY_URL, a URL not ending in /v1/notify, a key of the wrong shape, invalid JSON, or an oversized input.

Smoke test fails on 503 after wiring

SLACK_WIRED is true but the Worker answered 503, so a secret is missing. Check the secret names with pnpm exec wrangler secret list in app/ and re-run pnpm ops:push-secrets.