docs: onboarding overhaul, dedup, and error docs (#7711) (#10895)

* docs: fix CPU image tag (latest, not latest-cpu) Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: use canonical localai/localai registry in models guide Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: replace dead llama-stable backend with llama-cpp Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: correct mitm-proxy intercept config and redaction tier Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: fix text-to-audio endpoint and broken notice block Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: fix VAD example, stale FAQ, broken link, CLI list, whats-new dump Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: render advanced/reference section indexes (consolidate _index) Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: remove duplicate getting-started build/kubernetes pages Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: fold container image reference into installation/containers Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: remove stale advanced fine-tuning page (superseded by features/fine-tuning) Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: fold distribution/longcat/sound pages into their parents Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: make getting-started index accurate and complete Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: carry one concrete model through the getting-started path Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add end-to-end 'build your first agent' walkthrough Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add runtime errors reference; consolidate troubleshooting from FAQ Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add agent actions catalog Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: agent-scoped MCP, skills walkthrough, agentic disambiguation Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add concrete gallery install lines to media feature pages Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: merge installation into getting-started (URLs preserved via aliases) Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add Operations section; move operator pages and P2P API reference Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: journey-ordered top nav and grouped feature sections Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: add docs-with-code process gate (PR template + agent instructions) Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: remove em/en dashes from documentation prose Signed-off-by: Ettore Di Giacinto <mudler@localai.io> --------- Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
2026-08-01 02:49:51 -04:00 · 2026-07-17 22:08:20 +02:00
parent d3ea65a112
commit 40d35c0385
86 changed files with 1832 additions and 2114 deletions
--- a/docs/content/reference/api-errors.md
+++ b/docs/content/reference/api-errors.md
@@ -7,6 +7,10 @@ weight = 26

 This page documents the error responses returned by the LocalAI API. LocalAI supports multiple API formats (OpenAI, Anthropic, Open Responses), each with its own error structure.

+{{% notice note %}}
+For backend and runtime failure messages (a model that will not load, `could not load model`, `grpc service not ready`, `SIGILL`, VRAM out of memory, the model-load cooldown `503`), rather than API-envelope errors, see {{% relref "reference/runtime-errors" %}}.
+{{% /notice %}}
+
 ## Error Response Formats

 ### OpenAI-Compatible Format
@@ -90,7 +94,7 @@ The `/v1/responses` endpoint returns errors with this structure:

 ### Authentication Errors (401)

-When authentication is enabled — either via API keys (`LOCALAI_API_KEY`) or the user auth system (`LOCALAI_AUTH=true`) — API requests must include valid credentials. Credentials can be provided through:
+When authentication is enabled - either via API keys (`LOCALAI_API_KEY`) or the user auth system (`LOCALAI_AUTH=true`) - API requests must include valid credentials. Credentials can be provided through:

 - `Authorization: Bearer <key>` header (API key, user API key, or session ID)
 - `x-api-key: <key>` header
@@ -156,7 +160,7 @@ When `LOCALAI_OPAQUE_ERRORS=true` is set, all error responses return an empty bo

 ## Per-Endpoint Error Scenarios

-### Chat Completions — `POST /v1/chat/completions`
+### Chat Completions - `POST /v1/chat/completions`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -173,14 +177,14 @@ curl http://localhost:8080/v1/chat/completions \

 See also: [Text Generation]({{%relref "features/text-generation" %}})

-### Completions — `POST /v1/completions`
+### Completions - `POST /v1/completions`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
 | 400    | Invalid or malformed request body | `Bad Request`                       |
 | 500    | Backend inference failure       | `Internal Server Error`              |

-### Embeddings — `POST /v1/embeddings`
+### Embeddings - `POST /v1/embeddings`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -190,7 +194,7 @@ See also: [Text Generation]({{%relref "features/text-generation" %}})

 See also: [Embeddings]({{%relref "features/embeddings" %}})

-### Image Generation — `POST /v1/images/generations`
+### Image Generation - `POST /v1/images/generations`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -200,7 +204,7 @@ See also: [Embeddings]({{%relref "features/embeddings" %}})

 See also: [Image Generation]({{%relref "features/image-generation" %}})

-### Image Editing (Inpainting) — `POST /v1/images/edits`
+### Image Editing (Inpainting) - `POST /v1/images/edits`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -209,7 +213,7 @@ See also: [Image Generation]({{%relref "features/image-generation" %}})
 | 400    | Missing `mask` file             | `missing mask file`                   |
 | 500    | Storage preparation failure     | `failed to prepare storage`           |

-### Audio Transcription — `POST /v1/audio/transcriptions`
+### Audio Transcription - `POST /v1/audio/transcriptions`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -219,7 +223,7 @@ See also: [Image Generation]({{%relref "features/image-generation" %}})

 See also: [Audio to Text]({{%relref "features/audio-to-text" %}})

-### Text to Speech — `POST /v1/audio/speech`, `POST /tts`
+### Text to Speech - `POST /v1/audio/speech`, `POST /tts`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -229,7 +233,7 @@ See also: [Audio to Text]({{%relref "features/audio-to-text" %}})

 See also: [Text to Audio]({{%relref "features/text-to-audio" %}})

-### ElevenLabs TTS — `POST /v1/text-to-speech/:voice-id`
+### ElevenLabs TTS - `POST /v1/text-to-speech/:voice-id`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -237,7 +241,7 @@ See also: [Text to Audio]({{%relref "features/text-to-audio" %}})
 | 400    | Model not found in configuration | `Bad Request`                       |
 | 500    | Backend inference failure       | `Internal Server Error`              |

-### ElevenLabs Sound Generation — `POST /v1/sound-generation`
+### ElevenLabs Sound Generation - `POST /v1/sound-generation`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -245,7 +249,7 @@ See also: [Text to Audio]({{%relref "features/text-to-audio" %}})
 | 400    | Model not found in configuration | `Bad Request`                       |
 | 500    | Backend inference failure       | `Internal Server Error`              |

-### Reranking — `POST /v1/rerank`, `POST /jina/v1/rerank`
+### Reranking - `POST /v1/rerank`, `POST /jina/v1/rerank`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -255,7 +259,7 @@ See also: [Text to Audio]({{%relref "features/text-to-audio" %}})

 See also: [Reranker]({{%relref "features/reranker" %}})

-### Anthropic Messages — `POST /v1/messages`
+### Anthropic Messages - `POST /v1/messages`

 | Status | Cause                            | Error Type              | Example Message                                |
 |--------|----------------------------------|-------------------------|-------------------------------------------------|
@@ -282,7 +286,7 @@ curl http://localhost:8080/v1/messages \
 }
 ```

-### Open Responses — `POST /v1/responses`
+### Open Responses - `POST /v1/responses`

 | Status | Cause                               | Error Type              | Example Message                                        |
 |--------|-------------------------------------|-------------------------|--------------------------------------------------------|
@@ -315,14 +319,14 @@ curl http://localhost:8080/v1/responses \
 }
 ```

-### Open Responses — `GET /v1/responses/:id`
+### Open Responses - `GET /v1/responses/:id`

 | Status | Cause                     | Error Type              | Example Message                  |
 |--------|---------------------------|-------------------------|----------------------------------|
 | 400    | Missing response ID       | `invalid_request_error` | `response ID is required`        |
 | 404    | Response not found        | `not_found`             | `response not found: <id>`       |

-### Open Responses Events — `GET /v1/responses/:id/events`
+### Open Responses Events - `GET /v1/responses/:id/events`

 | Status | Cause                                | Error Type              | Example Message                                         |
 |--------|--------------------------------------|-------------------------|---------------------------------------------------------|
@@ -332,7 +336,7 @@ curl http://localhost:8080/v1/responses \
 | 404    | Response not found                   | `not_found`             | `response not found: <id>`                              |
 | 500    | Failed to retrieve events            | `server_error`          | `failed to get events: <details>`                       |

-### Object Detection — `POST /v1/detection`
+### Object Detection - `POST /v1/detection`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -342,7 +346,7 @@ curl http://localhost:8080/v1/responses \

 See also: [Object Detection]({{%relref "features/object-detection" %}})

-### Video Generation — `POST /v1/video/generations`
+### Video Generation - `POST /v1/video/generations`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -350,7 +354,7 @@ See also: [Object Detection]({{%relref "features/object-detection" %}})
 | 400    | Model not found in configuration | `Bad Request`                       |
 | 500    | Backend inference failure       | `Internal Server Error`              |

-### Voice Activity Detection — `POST /v1/audio/vad`
+### Voice Activity Detection - `POST /v1/audio/vad`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
@@ -358,14 +362,14 @@ See also: [Object Detection]({{%relref "features/object-detection" %}})
 | 400    | Model not found in configuration | `Bad Request`                       |
 | 500    | Backend inference failure       | `Internal Server Error`              |

-### Tokenize — `POST /v1/tokenize`
+### Tokenize - `POST /v1/tokenize`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|
 | 400    | Invalid or malformed request body | `Bad Request`                       |
 | 400    | Model not found in configuration | `Bad Request`                       |

-### Models — `GET /v1/models`, `GET /models`
+### Models - `GET /v1/models`, `GET /models`

 | Status | Cause                          | Example Message                       |
 |--------|--------------------------------|---------------------------------------|