docs(ai-transport): Add Troubleshooting page#3390
Merged
Merged
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
zknill
force-pushed
the
zak/ait-docs-troubleshooting
branch
from
4b6495d to
d013624
Compare
rainbowFi
approved these changes
May 29, 2026
Contributor
rainbowFi
left a comment
rainbowFi
left a comment
There was a problem hiding this comment.
Couple of suggestions but nothing blocking. Thanks!
|
|
||
| ## Channel namespace not configured for AI Transport <a id="namespace-not-configured"/> | ||
|
|
||
| **Symptom:** Clients see an empty assistant message, or a message containing only the first token. The server errors on subsequent publishes. The initial `message.create` succeeds, but the `message.append` operations that AI Transport uses to stream tokens fail because the namespace does not permit appends. This is the single most common AI Transport failure. |
Contributor
There was a problem hiding this comment.
I think we should include error code/error text here for searchability
| **Fix:** | ||
|
|
||
| - Enable the *Message annotations, updates, deletes, and appends* rule on the namespace. See [enable message updates and deletes](/docs/ai-transport/concepts/authentication#enable-updates-deletes) for the dashboard, Control API, and CLI steps. | ||
| - Note that enabling this rule causes messages to be persisted regardless of whether persistence is enabled, which increases usage. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Note that enabling this rule causes messages to be persisted regardless of whether persistence is enabled, which increases usage. | |
| - Note that enabling this rule automatically enables [message persistence](https://ably.com/docs/storage-history/storage#all-message-persistence) for all channels in the namespace, which increases usage. |
zknill
added a commit
that referenced
this pull request
Jun 1, 2026
Apply review feedback from PR #3390 on the namespace section of the AI Transport troubleshooting page. - Add the literal server error code (93002) and message text emitted when message.append is rejected on a namespace without the Message annotations, updates, deletes, and appends rule, so users hitting the failure find the page by searching their server logs. - Link the persistence note to the message-persistence reference, and clarify the rule causes persistence regardless of the namespace persistence toggle.
Add a single flat troubleshooting page covering the failure modes that produce most AI Transport support tickets. Entries follow the same shape — symptom, confirm, fix — and lead with the three must-check items: channel namespace rule, capability or token scope mismatch, and history retention. The operational entries below cover stuck turns, cancel-not-stopping, duplicate turns, oversized payloads, shared clientId across devices, out-of-sync branch selection, reconnect loops, mid-stream agent crashes, and suspended-state publishes. Each is verified against the ai-transport-js source so symptom and fix match real SDK behaviour (for example, the message status is streaming / finished — there is no aborted state). Link the page from the nav between "Going to production" and "API reference".
Apply review feedback from PR #3390 on the namespace section of the AI Transport troubleshooting page. - Add the literal server error code (93002) and message text emitted when message.append is rejected on a namespace without the Message annotations, updates, deletes, and appends rule, so users hitting the failure find the page by searching their server logs. - Link the persistence note to the message-persistence reference, and clarify the rule causes persistence regardless of the namespace persistence toggle.
zknill
force-pushed
the
zak/ait-docs-troubleshooting
branch
from
57cddca to
5281a79
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a single flat troubleshooting page covering the failure modes that produce most AI Transport support tickets. Entries follow the same shape — symptom, confirm, fix — and lead with the three must-check items: channel namespace rule, capability or token scope mismatch, and history retention.
The operational entries below cover stuck turns, cancel-not-stopping, duplicate turns, oversized payloads, shared clientId across devices, out-of-sync branch selection, reconnect loops, mid-stream agent crashes, and suspended-state publishes. Each is verified against the ai-transport-js source so symptom and fix match real SDK behaviour (for example, the message status is streaming / finished — there is no aborted state).
Link the page from the nav between "Going to production" and "API reference".