Knowledge Indexing Errors

See which files failed to embed instead of getting a silent empty result

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

1. 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?")

2. 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).

{
    '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.

Failure modes

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

Durable incremental index

The incremental-index state file (tracker.json) is saved atomically as of PR #5841. If a save fails part-way, the previous state file stays intact.

Before, a failed save could wipe the per-file record of stored chunks. The next incremental index would then treat every file as new and re-add it, leaving the old chunks in the vector store, so agents retrieved duplicate or stale content.

As of PR #6111, an unreadable or corrupt state file no longer resets to an empty state silently. FileTracker.load() logs a WARNING naming the state file and the error, and FileTracker.save() logs write failures instead of swallowing them. The empty-state fallback is unchanged — only the diagnostics are new, so a surprise full re-embed is traceable to its cause.

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}")

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

Related