Error dict shape
Stage methods do not raise on per-item failures. Instead they collect failures in the result’serrors list. Each error is a dict:
| Field | Description |
|---|---|
source | Source identifier (URL, file path, or chunk ID) |
source_kind | "url", "file", "chunk", etc. |
stage | Pipeline stage where the failure occurred |
error | Error message |
isRetryable | Whether the failure is safe to retry |
attempts | Number of attempts made |
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 "ragrails[voyage]" |
VOYAGE_API_KEY environment variable not set | Missing embedding credentials | Set the provider environment variable |
URL ingestion requires ... | Browser support not installed | Run rag.setup_url() or ragrails setup-url |
| Collection required | Vector DB needs a collection/index/class | Pass collection |
| Connection refused | Vector DB not running or wrong URL | Start the database and check url |
Retrying scrape failures
URL scrape failures withisRetryable: true are captured in a dead-letter queue and can be retried by passing result.dlq or a saved file path back to scrape().