Knowledge Indexing Errors

When you index a folder into a knowledge base, Knowledge.add() tells you which files failed so an outage in your embedding backend never looks like a successful import.

Quick Start

Simple usage

Point an agent at a folder and ask a question — indexing happens for you.

from praisonaiagents import Agent

agent = Agent(
    name="Docs Agent",
    instructions="Answer from the docs folder.",
    knowledge=["./docs"],
)

agent.start("What does the knowledge base cover?")

Check indexing succeeded

Call add() directly and inspect result["errors"] to see which files failed.

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.add("./docs")

if result["errors"]:
    for e in result["errors"]:
        print(f"failed: {e['file']} — {e['error']}")
else:
    print(f"indexed {len(result['results'])} chunk(s)")

How It Works

Knowledge.add() walks the directory, embeds each file, and returns the successes and failures together. A failed file is recorded instead of dropped, so a directory whose every file fails to embed no longer returns an empty-but-successful result.

Return shape

add() on a directory or list always returns these keys — errors is present even on success (as an empty list).

Key	Type	Description
`results`	`list`	Successfully stored chunk records
`relations`	`list`	Graph relations, when a graph store is configured
`errors`	`list[dict]`	`{'file': str, 'error': str}` entries, one per file that failed to index

{
    'results': [...],
    'relations': [],
    'errors': [
        {'file': '/abs/path/a.md',
         'error': 'Failed to generate embedding (model=text-embedding-3-small)'},
    ],
}

add([...]) aggregates errors from every input path, so one bad directory never hides errors from another.

errors is populated on the directory and list paths. A single-file add("./file.md") where every chunk fails raises RuntimeError instead of returning an errors list.

Failure modes

All files failed

Every entry lands in errors and results is empty. The log line names the first cause. Common causes: a wrong embedding model name, a revoked API key, or an exhausted quota.

Partial failure

results holds the chunks that succeeded and errors names only the ones that failed. The import is not rolled back.

Partial-chunk loss inside one file

When some of a file’s chunks embed and others are swallowed by the backend, the file still appears in results with the chunks that landed. Only when every chunk of a single-file add() fails does the call raise (see the next accordion) — a partial loss inside one file does not currently raise or add a per-chunk entry to errors.Guard against silent partial loss by treating a low results count for a large file as suspicious, and re-index the file if the embedding backend was degraded during the run.

Single-file add() where every chunk failed

The single-file path raises instead of returning silently:

RuntimeError: Stored nothing from {path}: all {n} chunk(s) failed (embedding/vector-store backend). See earlier logs.

Wrap the call in try / except RuntimeError if the caller wants to keep going.

List input

add([path1, path2, ...]) aggregates errors from every input path into one errors list.

User interaction flow

Bulk-import a docs folder before deployment, then gate the deploy on the result.

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.add("./docs")

assert not result["errors"], f"{len(result['errors'])} file(s) failed to index"
print(f"indexed {len(result['results'])} chunk(s)")

Run this in CI so a broken embedding backend fails the deploy instead of shipping an empty knowledge base.

Using `index()`

Knowledge.index() returns an IndexResult whose errors list carries whole-file failures as "{filepath}: {message}" strings.

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.index("./docs")

if not result.errors:
    print(f"indexed {result.files_indexed} file(s)")
else:
    for err in result.errors:
        print(f"failed: {err}")

result.success now reflects errors. index() now sets result.success = not result.errors. Previously success was never assigned, so it kept the dataclass default of True — a run where every file failed to embed still returned success=True with files_indexed=0 and each failure sitting in errors.If your CI relied on if result.success on a pre-PR version, it could report success on a fully failed index. Check if not result.errors for behaviour that is correct across versions.

Common Patterns

Fail fast in CI:

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.add("./docs")
assert not result["errors"]

Report and continue — keep what succeeded, log what didn’t:

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.add("./docs")
for e in result["errors"]:
    print(f"skipped: {e['file']} — {e['error']}")

Retry only the failed files:

from praisonaiagents.knowledge import Knowledge

k = Knowledge()
result = k.add("./docs")
for e in result["errors"]:
    k.add(e["file"])

Best Practices

Always inspect result['errors'] after a bulk import

A non-empty errors list is the only reliable signal that a file was skipped. Check it every time you index a folder.

Treat a non-empty errors list as an outage signal

Failures usually mean the embedding backend is down — a wrong model name, a revoked key, or an exhausted quota. Alert on it rather than logging it as a warning.

Catch RuntimeError for single-file calls

The errors list is populated on the directory and list paths. A single-file add() where every chunk fails raises RuntimeError, so wrap it in try / except if you need to continue.

Trust errors whether the backend raised or returned empty

errors is populated whether the store raised an exception or returned an empty result — embedding backends do both, and both are captured.

Knowledge

Core knowledge concepts and how agents use a knowledge base.

Knowledge Storage

Where knowledge persists and how to change the location.

Knowledge Backends

Choose and configure the vector store behind your knowledge base.

Incremental Indexing

See also — index() returns an IndexResult whose success and errors surface the same per-file failures for index() callers.

RAG CLI

The rag index wrapper surfaces these errors as a non-zero exit code.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Knowledge Indexing Errors

Quick Start

How It Works

Return shape

Failure modes

User interaction flow

Using `index()`

Common Patterns

Best Practices

Knowledge

Knowledge Storage

Knowledge Backends

Incremental Indexing

RAG CLI

​Quick Start

​How It Works

​Return shape

​Failure modes

​User interaction flow

​Using index()

​Common Patterns

​Best Practices

​Related

Knowledge

Knowledge Storage

Knowledge Backends

Incremental Indexing

RAG CLI

Quick Start

How It Works

Return shape

Failure modes

User interaction flow

Using `index()`

Common Patterns

Best Practices

Related