🤖 AI Troubleshooting

Audience: User, Org Admin, System Admin, Deployment Administrator, Developer, Support Related: Overview · Providers And Connections · Seeds And Usage

Check provider connection state, use-case capability, model/profile configuration, Seed balance and reservation state, provider error details, validation failures, and asset retention. Never place provider keys or full private prompts in support output.

Support Chat structured-response errors

If Support Chat reports that a provider returned a structured response Blackcap could not parse, do not assume the user's punctuation or special characters are the cause. Blackcap requests strict JSON-schema output and user/documentation text is transmitted as normal provider input rather than manually concatenated JSON.

For OpenAI, first check the Support Chat AI Usage row for the failure category and provider request/response IDs, then check the application log for the corresponding safe diagnostics. In particular, distinguish:

• context_limit with incomplete_reason=max_output_tokens: the model used the configured output budget before completing its JSON object. Increase the Support Chat Maximum Output Tokens setting or lower reasoning effort and retry.
• invalid_response with a JSON error line/column: the provider returned text that was not valid JSON even after harmless wrapper handling. Use the provider response ID when investigating the upstream request.
• safety_rejection: the provider declined the request; this is not a JSON escaping problem.

Blackcap accepts harmless UTF-8 BOM, Markdown code-fence, and surrounding presentation wrappers, but it deliberately does not guess how to repair malformed quotes or escapes because doing so could change the model's intended response.

A model appears in the provider catalog but does not work

A provider's model-list API is not always proof that the same credential can use that model on every API surface. Blackcap therefore combines its curated capability catalog with the provider's live model inventory and, for inexpensive text use cases, an endpoint-specific capability probe.

In Configuration → Platform → AI, open the provider details to compare the models Blackcap knows about with the models verified for that credential. A known-but-unusable model remains readable but is marked Unavailable with a red diagonal slash. Use-case badges show whether Blackcap expects the model to serve 🖼️ Recipe Image, 🎬 Social Recipe, 🛟 Support Chat, or 🎙️ Transcription.

If a text model is unexpectedly unavailable:

1. Use the provider Test action to force a fresh availability check instead of waiting for the cache to expire.
2. Confirm the quality profile uses a model marked usable for that specific use case.
3. Check the application log for the safe provider failure category and HTTP status. A model may be visible in the provider inventory but still return 404/model-unavailable on the endpoint Blackcap uses.
4. Do not expect Blackcap to silently fall back to another model. The quality profile's selected model is authoritative so provider/model changes remain explicit and auditable.

Changing the provider connection or model on a quality profile preserves the other compatible profile settings. Blackcap should not reset unrelated output, timeout, Support Chat, or social-media limits merely because the model selection changed.