Tavina

Provider response troubleshooting

๐Ÿ“– This content is synced from the Tavina Handbook.
The canonical version always lives at https://tavina.ai/docs/support/troubleshooting/provider-responses

Provider response troubleshooting

Use this page when Tavina returns a degraded provider notice, shows a missing visible-answer notice, says it used a backup model, or records a privacy-safe provider diagnostic.

Tavina-managed AI-service defaults

Tavina-managed accounts use source-managed AI-service defaults. When engineering changes one of those defaults, the normal deploy and managed-resync path may apply the new value to both newly provisioned accounts and existing Tavina-managed accounts. For the dev-track GLM 5.3 Flash route, the current managed reasoning-effort default is `high`; `max` should be treated as an explicit override, a stale managed value, or a pre-update runtime state unless a later release note changes the default again.

This guidance is for support-safe triage only. Do not ask users for provider keys, raw request payloads, hidden reasoning, internal hostnames, or private configuration files. If an AI-service behavior changes near a managed-default release window, record the visible notice, timestamp, subscriber, safe provider/model labels, and whether the account is Tavina-managed or bring-your-own-key before escalating.

This page is support context only. Do not quote it as customer policy, and do not ask users for provider keys, raw provider payloads, secret headers, private prompts, or full diagnostic logs.

Notice types

| Notice or signal | What it means | First support action |
| — | — | — |
| Degraded provider notice on an answer | Tavina received a completion only after retrying a failed streaming response as a non-streaming request. | Confirm the answer is visibly marked as degraded and ask whether the user wants to retry or continue with caution. |
| Missing visible-answer notice | Tavina received internal provider output but could not recover a visible assistant answer within the allowed continuation budget. | Record the timestamp, subscriber, visible notice, and safe diagnostic fields; do not ask for hidden reasoning text. |
| Malformed tool-call recovery notice | The model leaked tool-call markup into the visible answer text; Tavina classified it, attempted recovery (surgical correction or a bounded retry), and only showed a short replacement notice when nothing recoverable remained. | Confirm which outcome the user saw (intact corrected answer vs. recovery notice), record time and subscriber, and check `malformed_markup_recovery_*` diagnostics when exposed. |
| Provider fallback notice | Tavina used a configured backup model after the primary model failed its allowed attempts. | Confirm the visible fallback notice, the time, and whether the model setting was recently changed. |
| Scheduled-report deadline notice | A scheduled routine report ran into its time budget before it could finish, so Tavina stopped the turn honestly and recorded the run as a failure with a deadline reason instead of letting it hang or reporting success. | Record timestamp, subscriber, and which routine; confirm the firing history shows a failure with a deadline reason. Escalate if the same routine repeatedly hits its deadline. |
| Scheduled no-deliverable notice | A scheduled routine ended with only progress narration or a short, unverified failure claim (for example a bare “the scan timed out”) and no completed work behind it, so Tavina did not accept it as the routine’s deliverable and showed this honest notice instead; the run is recorded as a failure and the next scheduled run is unaffected. A complete report that merely mentions that one source timed out is delivered as normal and is never replaced by this notice. Invented system-warning text is always replaced, whatever the length. | Record timestamp, subscriber, and which routine; confirm the firing history shows a failed run with an invalid-output reason rather than success; check whether the claimed failure matched any real tool failure in that turn. |
| Scheduled failure-only report | A scheduled routine produced no report but honestly explained a real tool failure from that run. The explanation is shown as written, and the run is recorded as a failure in its firing history, however long the explanation is. | Record timestamp, subscriber, and which routine; confirm the firing history shows a failed run; check which tool failed and escalate if the same routine fails repeatedly. |
| 401 or 403 provider error | The provider treated the request as unauthorized or forbidden. | Explain that Tavina should not use a backup model for auth-class failures; ask the user to review the provider key or provider account permissions. |
| Provider request rejection diagnostic | Tavina recorded a structure-only shape for a provider 4xx or 5xx rejection. | Use the diagnostic to compare request shape and provider status without exposing message content or secrets. |

Degraded stream-to-non-stream answers

A degraded notice means Tavina detected that the provider streaming path failed, retried with a non-streaming request, and received a completion from that fallback path. The answer should be visibly prefixed with a degraded-mode notice, and the assistant turn should carry degraded metadata for later diagnosis.

Support expectations:

1. Confirm the user saw a degraded notice rather than a normal answer.
2. Ask for the approximate time, subscriber context, visible provider/model name if shown, and whether the user retried.
3. Treat the answer as potentially useful but lower-confidence. Encourage the user to verify important output.
4. Escalate if degraded notices repeat for the same provider/model or if fallback answers omit the visible degraded prefix.

Do not collect the user’s private message content unless the user voluntarily provides a minimal, non-sensitive reproduction.

Missing visible-answer notices

A missing visible-answer notice means Tavina received provider output that did not include user-visible answer text. Tavina first makes bounded final-answer recovery attempts โ€” follow-up requests grounded in your original question and any completed tool results. Recovery room scales with how long the turn already ran, so long-running turns get a proportionally larger recovery budget (currently up to two attempts within a default window of about two minutes). Recovery never re-runs tools or repeats completed actions, and it never shows hidden reasoning as the answer. If recovery still cannot produce a visible answer, Tavina shows a concise response-generation notice that says the answer text was missing; it should not say an action or tool failed unless there is separate evidence of an actual action failure. A turn like this counts as a recoverable failure, not a success, even though the provider exchange itself completed normally.

Support expectations:

1. Confirm the visible notice distinguishes missing answer text from a failed action or failed tool run.
2. Collect the approximate time, subscriber context, visible provider/model label if shown, and whether the user retried successfully.
3. Look for the redacted `visible_answer_missing_fallback` diagnostic when tooling exposes it. Safe fields can include whether reasoning was present, character counts, tool-call count, how recovery ended (recovered, failed, timed out, or disabled), fallback reason code, and the final outcome โ€” a turn counts as completed only when a usable answer was actually delivered.
4. Do not collect or expose hidden reasoning text, private prompts, raw provider payloads, or full diagnostic logs.
5. Escalate if the notice repeats for the same subscriber/model, if the notice claims an action failed without a matching action/tool failure, or if diagnostics contain user content or secrets.

Malformed tool-call recovery

Occasionally a model places tool-call markup into the visible answer text instead of a proper tool call. Tavina now detects this as a parse issue, attempts recovery before any answer guard runs, and prefers keeping the user’s answer: it surgically strips the stray markup while preserving the actual answer content, or makes one bounded retry using the detected tool intent. A short replacement notice appears only when no recoverable answer content or tool intent remains.

Support expectations:

1. Ask which outcome the user saw: an intact answer (markup cleaned) or a concise recovery notice.
2. Collect the approximate time and subscriber context; the failure is intermittent and pressure-sensitive rather than permanent.
3. A turn that ends with a recovery notice is counted as a degraded outcome, not a successful answer โ€” transport completed but the answer did not.
4. Safe diagnostics include `malformed_markup_recovery_evaluated` / `_surfaced` / `_retry_started` events, a content hash, and the reason code `tool_call_markup_in_visible_text`; do not collect raw markup text or private message content.
5. Escalate if recovery notices repeat for the same subscriber/model, especially around very large tool inventories or heavy sessions.

BYOK backup model fallback

For bring-your-own-key provider settings, a subscriber may configure a backup model from the same provider and key, and may also order their own saved providers into a cross-provider fallback chain (tavina/tavina#2507). Tavina should try the active provider’s primary model twice before falling back to the backup model, then continue down the subscriber’s fallback chain, each provider with its own key. Tavina should not use fallback for authentication-class failures such as 401 or 403 responses.

When fallback is used, Tavina should surface a fallback notice and record truthful metadata such as the served model and whether fallback was used. If the visible notice or diagnostics disagree with the user’s configured models, escalate with the timestamp and safe metadata only.

Provider request rejection diagnostics

Tavina may record privacy-safe request rejection shapes for provider 4xx and 5xx responses. On the dev track this capture is default-on; production use is opt-in and bounded by retention limits.

These diagnostics are for support and engineering triage. They should record structure only, such as request mode, missing or extra high-level fields, provider status class, model identifiers, and retry/fallback and recovery state. They also distinguish a successful transport-level exchange from a useful answer: a completed provider response with no visible answer text is a transport success but an empty-answer outcome, and streaming errors are never reported as unqualified streaming successes. They must avoid message content, secrets, PII, raw tool schemas, raw authorization headers, and raw provider payloads.

Safe collection checklist:

  • timestamp or short incident window;
  • provider and model labels shown to the user or in safe metadata;
  • whether the request was streaming or non-streaming;
  • whether Tavina reported degraded mode, fallback, or no fallback;
  • whether Tavina reported a missing visible-answer fallback and whether continuation was attempted;
  • provider status class, such as 4xx or 5xx, without raw payload details;
  • the diagnostic event identifier if support tooling exposes one.

Unsafe to collect:

  • provider API keys, OAuth codes, bearer tokens, cookies, or authorization headers;
  • full user prompts, private documents, or contact details;
  • raw tool schemas or raw provider request/response bodies;
  • internal hostnames, IP addresses, deployment paths, or secret configuration values.

Escalation triggers

Escalate to engineering when:

  • degraded notices repeat for the same provider/model after a retry;
  • the fallback notice appears for a 401 or 403 auth-class failure;
  • `model_served` or fallback metadata is missing or contradicts the visible notice;
  • diagnostics appear to include message content, secrets, PII, or raw tool schemas;
  • missing visible-answer notices repeat or imply an action/tool failure without matching action/tool failure evidence;
  • stream and non-stream replay/diff results point to a provider-specific request-shape mismatch.

Include only privacy-safe shape data and the incident window in the escalation.

Related pages

Scroll to Top