lossless-monorepo/agent-skills/chroma-agent-skills/src/chroma-local/templates/error-handling

Error Handling

Local Chroma operations can fail for various reasons: the local server may not be running, collections may be missing, or input data may be invalid. This guide covers the common local error scenarios and how to handle them.

{{CODE:imports}}

Error types

Python uses specific exception classes:

• chromadb.errors.NotFoundError - Collection, tenant, or database doesn’t exist
• ValueError - Invalid collection name or duplicate creation attempt

TypeScript throws standard Error objects with descriptive messages. Check the error message to determine the cause.

Connection errors

Connection failures occur when the client can’t reach the Chroma server. This is common during startup or when network issues occur.

{{CODE:connection-errors}}

Collection not found

When working with collections that may not exist, handle the NotFoundError (Python) or catch the error and check its message (TypeScript).

{{CODE:collection-not-found}}

Safe collection access pattern

The getOrCreateCollection method is the recommended way to avoid “not found” errors entirely. Use getCollection only when you specifically need to verify a collection exists.

{{CODE:safe-collection-access}}

Validation errors

Chroma validates data before operations. Common validation failures include:

• Document content exceeding 16KB
• Embedding dimensions not matching the collection
• Metadata exceeding limits (4KB total, 32 keys max)
• Invalid collection names

{{CODE:validation-errors}}

Batch operation failures

When adding or upserting multiple documents, a single invalid document fails the entire batch. Validate data before sending, or implement retry logic for partial failures.

{{CODE:batch-operations}}

Defensive patterns summary