> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ragrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Common Ragrails error shapes and fixes.

Ragrails uses two error shapes.

Stage methods usually return per-item failures in the result's `errors` list. REST requests that fail before a stage can run return an exception envelope.

## Stage Error Dict

Pipeline stages do not raise for every item-level failure. They collect failures in `errors` and continue when possible.

| Field               | Description                                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`            | Source identifier: URL, file path, query, chunk ID, or empty string when the error is global                                                                    |
| `source_kind`       | Error domain, e.g. `path`, `bytes`, `url`, `api`, `markdown`, `chunk`, `embedded_chunk`, `stored_chunk`, `query`, or `chat`                                     |
| `stage`             | Stage where the failure occurred: `validate`, `fetch`, `convert`, `embed`, `store`, `edit`, `delete`, `retrieve`, `rewrite`, `rerank`, `generate`, or `quality` |
| `error`             | Human-readable error message                                                                                                                                    |
| `isRetryable`       | Whether retrying the same item can reasonably succeed                                                                                                           |
| `attempts`          | Number of attempts made                                                                                                                                         |
| `retry_input`       | Optional retry payload for URL/API failures                                                                                                                     |
| `mode` / `root_url` | Optional URL crawl context                                                                                                                                      |

<CodeGroup>
  ```json Validation theme={null}
  {
    "failed": 1,
    "errors": [
      {
        "source": "policy.md",
        "source_kind": "markdown",
        "stage": "validate",
        "error": "chunk item text must be a non-empty string",
        "isRetryable": false,
        "attempts": 1
      }
    ]
  }
  ```

  ```json Retryable theme={null}
  {
    "failed": 1,
    "errors": [
      {
        "source": "https://example.com/docs",
        "source_kind": "url",
        "stage": "fetch",
        "error": "Timeout while loading page",
        "isRetryable": true,
        "attempts": 1,
        "retry_input": {"url": "https://example.com/docs", "mode": "full"}
      }
    ]
  }
  ```
</CodeGroup>

## REST Exception Envelope

If a REST request fails before the stage returns a result, the server returns an exception envelope.

<CodeGroup>
  ```json 400 theme={null}
  {
    "error": {
      "type": "ValueError",
      "message": "chunk_overlap must be smaller than chunk_size"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "type": "FileNotFoundError",
      "message": "files/missing.pdf"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "type": "RuntimeError",
      "message": "Chunking dependencies are missing. Reinstall with: pip install -U ragrails"
    }
  }
  ```
</CodeGroup>

## Common Setup Errors

| Message                                       | Cause                                      | Fix                                                                                                |
| --------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `... requires optional dependencies`          | A provider or URL extra is not installed   | Install the matching extra, e.g. `pip install "ragrails[url]"` or `pip install "ragrails[voyage]"` |
| `VOYAGE_API_KEY environment variable not set` | Missing embedding credentials              | Set the provider environment variable                                                              |
| `OPENAI_API_KEY environment variable not set` | Missing LLM credentials                    | Set the provider environment variable                                                              |
| `URL ingestion requires ...`                  | Browser support is not installed           | Run `rag.setup_url()` or `ragrails setup-url`                                                      |
| `collection is required`                      | Vector DB needs a collection/index/class   | Pass `collection`                                                                                  |
| `Connection refused`                          | Vector DB is not running or `url` is wrong | Start the database and check `url`                                                                 |

## Retrying Scrape/API Failures

URL and API failures can include `isRetryable: true` and a `retry_input` payload.

URL scrape failures with `isRetryable: true` are captured in a [dead-letter queue](/usage/sdk/extraction#dead-letter-queue-dlq) and can be retried by passing `result.dlq` or a saved file path back to `scrape()`.