Troubleshooting

This section is for common production questions and “it does not work” scenarios.

If you need a mapping of typical failures to codes and causes, see Error codes.

“I subscribed but I do not receive messages”

Check in this order:

1. Same tenant? Tenant must match exactly. No wildcards for tenants.
2. Same channel? Verify spelling and separators.
3. Token allows it? Your token must allow that tenant and channel rule (see Permissions model).
4. Join window: if a writer published right after you subscribed, early messages may be missed due to subscription propagation (see Delivery semantics).
5. Are you actually connected? Some clients silently reconnect and lose subscriptions.

“Why do I get disconnected?”

Common reasons:

• Slow consumer: your client does not read fast enough; buffers fill up.
• Network instability: transient connectivity issues.
• Token expired / revoked: reconnect auth fails.
• Policy violation: forbidden publish/subscribe attempt (depends on deployment; may close connection).

Recommendations:

• keep receive loop fast (do not block),
• reconnect with backoff and resubscribe,
• add observability (see Observability).

“Invalid token”

Typical causes:

• token string is malformed (not AT_<id>_<secret>)
• token expired (expires_at in the past)
• token revoked
• token restricted by IP/region/origin and your client does not match

See Tokens.

“Publish works but subscribe does not” (or vice versa)

Publish and subscribe permissions are separate:

• allow_channels_pub vs allow_channels_sub

Check the token grants and confirm the correct tenant is used.

Troubleshooting