CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-dev-langchain4j--langchain4j-chroma

LangChain4j integration for Chroma embedding store enabling storage, retrieval, and similarity search of vector embeddings with metadata filtering support for both API V1 and V2.

Overview
Eval results
Files

error-handling.mddocs/guides/

Error Handling Guide

Comprehensive guide to handling errors when using ChromaEmbeddingStore.

Common Exception Types

Connection Errors

try {
    ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
        .baseUrl("http://localhost:8000")
        .build();

    store.add(embedding);

} catch (java.net.http.HttpConnectTimeoutException e) {
    // Cannot connect to Chroma server
    System.err.println("Connection failed: " + e.getMessage());
    // Action: Check server is running, verify baseUrl

} catch (java.net.ConnectException e) {
    // Connection refused
    System.err.println("Connection refused: " + e.getMessage());
    // Action: Ensure Chroma server is started
}

Timeout Errors

try {
    EmbeddingSearchResult<TextSegment> result = store.search(request);

} catch (java.net.http.HttpTimeoutException e) {
    // Operation exceeded timeout
    System.err.println("Operation timed out: " + e.getMessage());
    // Action: Increase timeout or reduce operation size
}

Configuration Errors

try {
    ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
        // Missing baseUrl
        .collectionName("test")
        .build();

} catch (IllegalArgumentException e) {
    // Invalid configuration
    System.err.println("Configuration error: " + e.getMessage());
    // Action: Fix configuration
}

Error Handling Patterns

Basic Try-Catch

public void addDocument(Embedding embedding, TextSegment segment) {
    try {
        store.add(embedding, segment);
    } catch (Exception e) {
        System.err.println("Failed to add document: " + e.getMessage());
        e.printStackTrace();
    }
}

Retry Logic

public String addWithRetry(
    Embedding embedding,
    TextSegment segment,
    int maxRetries
) {
    int attempt = 0;
    Exception lastException = null;

    while (attempt < maxRetries) {
        try {
            return store.add(embedding, segment);

        } catch (java.net.http.HttpTimeoutException |
                 java.net.http.HttpConnectTimeoutException e) {
            lastException = e;
            attempt++;

            if (attempt < maxRetries) {
                System.out.println("Retry " + attempt + " of " + maxRetries);
                try {
                    Thread.sleep(1000 * attempt);  // Exponential backoff
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Interrupted during retry", ie);
                }
            }

        } catch (Exception e) {
            // Non-retryable error
            throw new RuntimeException("Failed to add document", e);
        }
    }

    throw new RuntimeException(
        "Failed after " + maxRetries + " attempts",
        lastException
    );
}

Circuit Breaker Pattern

public class CircuitBreakerStore {

    private final ChromaEmbeddingStore store;
    private int failureCount = 0;
    private long lastFailureTime = 0;
    private static final int FAILURE_THRESHOLD = 5;
    private static final long RESET_TIMEOUT = 60000;  // 1 minute

    private boolean isCircuitOpen() {
        if (failureCount >= FAILURE_THRESHOLD) {
            long timeSinceFailure = System.currentTimeMillis() - lastFailureTime;
            if (timeSinceFailure < RESET_TIMEOUT) {
                return true;  // Circuit still open
            } else {
                // Try to reset
                failureCount = 0;
                return false;
            }
        }
        return false;
    }

    public String add(Embedding embedding, TextSegment segment) {
        if (isCircuitOpen()) {
            throw new RuntimeException("Circuit breaker is open");
        }

        try {
            String id = store.add(embedding, segment);
            failureCount = 0;  // Reset on success
            return id;

        } catch (Exception e) {
            failureCount++;
            lastFailureTime = System.currentTimeMillis();
            throw e;
        }
    }
}

Graceful Degradation

public class ResilientRAG {

    private final ChromaEmbeddingStore primaryStore;
    private final ChromaEmbeddingStore backupStore;  // Optional backup

    public EmbeddingSearchResult<TextSegment> search(
        EmbeddingSearchRequest request
    ) {
        try {
            return primaryStore.search(request);

        } catch (Exception e) {
            System.err.println("Primary store failed: " + e.getMessage());

            if (backupStore != null) {
                try {
                    System.out.println("Trying backup store");
                    return backupStore.search(request);
                } catch (Exception backupError) {
                    System.err.println("Backup store also failed");
                }
            }

            // Return empty result instead of throwing
            return new EmbeddingSearchResult<>(Collections.emptyList());
        }
    }
}

Specific Error Scenarios

Dimension Mismatch

try {
    // First embedding: 3 dimensions
    store.add(Embedding.from(new float[]{0.1f, 0.2f, 0.3f}));

    // Second embedding: 4 dimensions (will fail)
    store.add(Embedding.from(new float[]{0.1f, 0.2f, 0.3f, 0.4f}));

} catch (RuntimeException e) {
    if (e.getMessage().contains("dimension")) {
        System.err.println("Embedding dimension mismatch");
        // Action: Ensure all embeddings have same dimensions
    }
}

Prevention:

public class EmbeddingValidator {

    private Integer expectedDimension = null;

    public void validateAndAdd(Embedding embedding) {
        int dimension = embedding.vector().length;

        if (expectedDimension == null) {
            expectedDimension = dimension;
        } else if (dimension != expectedDimension) {
            throw new IllegalArgumentException(
                "Expected dimension " + expectedDimension +
                " but got " + dimension
            );
        }

        store.add(embedding);
    }
}

Invalid Filter Errors

try {
    // Invalid: comparison operator on string
    Filter filter = metadataKey("name").isGreaterThan("M");

    EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
        .queryEmbedding(queryEmbedding)
        .filter(filter)
        .build();

    store.search(request);

} catch (RuntimeException e) {
    System.err.println("Invalid filter: " + e.getMessage());
    // Action: Use isEqualTo or isIn for string values
}

Prevention:

// For strings, use equality or collection filters
Filter validFilter = metadataKey("name").isEqualTo("Smith");
Filter validFilter2 = metadataKey("name").isIn(names);

// For numbers, comparison operators work
Filter numericFilter = metadataKey("year").isGreaterThan(2020);

Collection/Server Errors

try {
    store.search(request);

} catch (RuntimeException e) {
    String message = e.getMessage().toLowerCase();

    if (message.contains("collection")) {
        System.err.println("Collection error: " + e.getMessage());
        // Collection may have been deleted or corrupted

    } else if (message.contains("404") || message.contains("not found")) {
        System.err.println("Resource not found: " + e.getMessage());

    } else if (message.contains("500") || message.contains("internal server")) {
        System.err.println("Chroma server error: " + e.getMessage());
        // Check Chroma server logs

    } else {
        System.err.println("Unknown error: " + e.getMessage());
    }
}

Batch Operation Error Handling

Partial Failure Handling

public class BatchProcessor {

    public List<String> addAllWithErrorHandling(
        List<Embedding> embeddings,
        List<TextSegment> segments
    ) {
        try {
            return store.addAll(embeddings, segments);

        } catch (Exception e) {
            System.err.println("Batch add failed: " + e.getMessage());

            // Fallback: add individually to identify failures
            List<String> ids = new ArrayList<>();
            for (int i = 0; i < embeddings.size(); i++) {
                try {
                    String id = store.add(embeddings.get(i), segments.get(i));
                    ids.add(id);
                } catch (Exception itemError) {
                    System.err.println("Failed item " + i + ": " +
                                     itemError.getMessage());
                    ids.add(null);  // Mark failure
                }
            }
            return ids;
        }
    }
}

Chunked Batch Processing

public void addAllInChunks(
    List<Embedding> embeddings,
    List<TextSegment> segments,
    int chunkSize
) {
    for (int i = 0; i < embeddings.size(); i += chunkSize) {
        int end = Math.min(i + chunkSize, embeddings.size());

        try {
            List<Embedding> embBatch = embeddings.subList(i, end);
            List<TextSegment> segBatch = segments.subList(i, end);

            store.addAll(embBatch, segBatch);
            System.out.println("Processed chunk " + (i / chunkSize + 1));

        } catch (Exception e) {
            System.err.println("Chunk " + (i / chunkSize + 1) +
                             " failed: " + e.getMessage());
            // Continue with next chunk or handle failure
        }
    }
}

Logging and Monitoring

Structured Error Logging

public class MonitoredStore {

    private final ChromaEmbeddingStore store;
    private final Logger logger;

    public String add(Embedding embedding, TextSegment segment) {
        long startTime = System.currentTimeMillis();

        try {
            String id = store.add(embedding, segment);
            long duration = System.currentTimeMillis() - startTime;

            logger.info("Add successful - duration: {}ms", duration);
            return id;

        } catch (java.net.http.HttpTimeoutException e) {
            long duration = System.currentTimeMillis() - startTime;
            logger.error("Add timeout after {}ms: {}", duration, e.getMessage());
            throw e;

        } catch (Exception e) {
            logger.error("Add failed: {}", e.getMessage(), e);
            throw e;
        }
    }
}

Metrics Collection

public class MetricsStore {

    private final AtomicLong successCount = new AtomicLong();
    private final AtomicLong failureCount = new AtomicLong();
    private final AtomicLong totalDuration = new AtomicLong();

    public String addWithMetrics(Embedding embedding, TextSegment segment) {
        long start = System.currentTimeMillis();

        try {
            String id = store.add(embedding, segment);
            successCount.incrementAndGet();
            totalDuration.addAndGet(System.currentTimeMillis() - start);
            return id;

        } catch (Exception e) {
            failureCount.incrementAndGet();
            throw e;
        }
    }

    public void printMetrics() {
        long success = successCount.get();
        long failure = failureCount.get();
        long total = success + failure;
        long avgDuration = total > 0 ? totalDuration.get() / success : 0;

        System.out.println("Success: " + success);
        System.out.println("Failure: " + failure);
        System.out.println("Success rate: " +
                         (total > 0 ? (success * 100.0 / total) : 0) + "%");
        System.out.println("Avg duration: " + avgDuration + "ms");
    }
}

Testing Error Conditions

Simulating Errors

@Test
public void testConnectionError() {
    // Use invalid URL to test connection error handling
    ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
        .baseUrl("http://invalid-host:9999")
        .timeout(Duration.ofSeconds(1))
        .build();

    assertThrows(Exception.class, () -> {
        store.add(Embedding.from(new float[]{1.0f, 0.0f, 0.0f}));
    });
}

@Test
public void testTimeoutError() {
    ChromaEmbeddingStore store = ChromaEmbeddingStore.builder()
        .baseUrl("http://localhost:8000")
        .timeout(Duration.ofMillis(1))  // Very short timeout
        .build();

    // May timeout with large operations
    List<Embedding> largeList = generateLargeEmbeddingList();

    assertThrows(java.net.http.HttpTimeoutException.class, () -> {
        store.addAll(largeList);
    });
}

Best Practices

  1. Always handle exceptions - Network operations can fail
  2. Use specific exception types - Catch specific exceptions first
  3. Implement retry logic - For transient failures
  4. Log errors comprehensively - Include context and stack traces
  5. Monitor error rates - Track and alert on high failure rates
  6. Test error conditions - Verify error handling works
  7. Provide fallbacks - Degrade gracefully when possible
  8. Validate input early - Catch errors before sending to server
  9. Set appropriate timeouts - Balance between reliability and responsiveness
  10. Document error scenarios - Help users understand failures

Related

  • Configuration Guide - Proper configuration
  • Performance Guide - Timeout tuning
  • ChromaEmbeddingStore API - Method signatures

External Resources

  • LangChain4j Error Handling
  • Chroma Troubleshooting

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-chroma@1.11.0

docs

guides

batch-operations.md

configuration.md

error-handling.md

filtering.md

metadata.md

migration.md

performance.md

rag-pattern.md

semantic-search.md

index.md

tile.json