Troubleshooting

Most production issues fall into one of four buckets: invalid configuration, malformed tool arguments, repeated tool-call loops, or backend timeouts. Use the guide below to decide whether to retry, fix code, or alert your team.

Invalid Config

• Blank or invalid base URL: the SDK throws MilkeyConfigError when baseUrl is missing or empty.
• Blank or invalid API key: missing or empty keys also surface as MilkeyConfigError.
• Reference slug format errors: getSkillReference expects skill-slug/reference-slug.

Tool Loop Issues

Inline mode is application-managed orchestration. If the model keeps asking for tools, your app must decide when to stop.

• Assistant returned tool calls but no text: this is normal. Continue the tool loop and append tool outputs.
• Tool result returned but the model requests another tool: continue until you hit a bounded max turn count.
• Repeated identical tool calls: break recursion and force a final answer or disable tools on the final summarization turn.
• No tool calls at all: this is also valid. Let the model answer normally.

Timeouts & Backend Errors

• MilkeyTimeoutError: the request exceeded timeoutMs. Review network conditions, provider retry settings, and backend timing.
• MilkeyProblemError: the backend returned an RFC 9457 problem response. Inspect problem.title, problem.detail, and status.
• MilkeyResponseError: non-200 response with raw body content. Capture the status and body in logs.
• MilkeyToolCallError: the provider returned malformed JSON or non-object tool arguments. This is a tool-call parsing issue, not a retry-first network issue.

For quota issues, the API may return 429 Too Many Requests. Treat that as a recoverable operational event with backoff and alerting, not as a generic connection failure.

Support

If the issue persists, include the provider name, tool name, error class, and a sanitized trace when contacting support.

You can also review the SDK guide for the expected inline and hosted mode control flow.