diff --git a/packages/kilo-docs/pages/ai-providers/index.md b/packages/kilo-docs/pages/ai-providers/index.md
index c7fb9d6349a8..513272d090b9 100644
--- a/packages/kilo-docs/pages/ai-providers/index.md
+++ b/packages/kilo-docs/pages/ai-providers/index.md
@@ -91,6 +91,20 @@ To allow only specific providers and disable everything else, use `enabled_provi
 
 Both fields accept provider IDs — the lowercase identifier used in the `provider/model` format (e.g. `kilo`, `anthropic`, `openai`, `google`, `groq`).
 
+## When a provider fails to load
+
+If Kilo Code cannot fetch a provider's models — for example, because the provider rejected your credentials or its API is unreachable — it keeps the provider visible and shows the reason instead of hiding it. The reason appears wherever you pick a provider: the VS Code provider list and model selector, and the TUI provider picker. In the CLI, the same details are written to the log file; read them with `kilo --print-logs --log-level DEBUG`.
+
+| Reason | What it means |
+|---|---|
+| Credentials rejected | The provider rejected your credentials (for example, HTTP 401). Sign in again to refresh them. |
+| Not signed in | The provider needs a sign-in before its models load. |
+| Couldn't reach the provider | A network error blocked the request. Check your connection and try again. |
+| Provider error | The provider returned an unexpected HTTP status. |
+| Unexpected response | The provider returned data Kilo Code could not read. |
+
+When credentials were rejected, Kilo Code offers to sign in again from the same view.
+
 ## Next Steps
 
 - **New to Kilo Code?** Start with the [Kilo Code provider](/docs/ai-providers/kilocode) - no setup required