Module misconfiguration 

Misconfiguration-first failure classification.

For every runtime failure, callers must check settings/config before retrying. This module is the shared detector: given an ErrorCategory plus the raw error text, it returns actionable ConfigGuidance when the failure is caused by user misconfiguration (bad credentials, unknown model/provider, invalid base_url, malformed vtcode.toml, bad MCP or sampling params).

Transient failures (network, timeout, rate-limit, 5xx) return None so existing retry policy applies unchanged. LLM argument mistakes (bad patch, bad tool args) also return None — they lack config markers.

Structs

ConfigGuidance

Actionable guidance for fixing a misconfiguration.

Enums

MisconfigurationKind

Kind of user misconfiguration detected.

Functions

detect_misconfiguration

Return guidance when message indicates user misconfiguration.

detect_misconfiguration_in_anyhow

Detect configuration failures from an error that may still retain its typed provider cause. Provider metadata often contains the actionable model or credential code even when the Display message is only a generic HTTP failure.

detect_misconfiguration_in_llm_error

Detect configuration failures using both the primary LLM error message and provider metadata such as model_not_found or invalid_api_key.

is_misconfiguration

Convenience predicate for fail-fast checks.