Errors & Platform Limits

​

Quick Diagnosis

• Can’t upload? see Upload Errors
• Search not working? go to Search Errors
• Slow performance? look at Performance Issues
• Wrong results? Check Retrieval Quality

​

API Errors

​

Common errors (Add)

​

Common errors (Search)

​

Application-Level Issues

​

Performance issues

​

Slow Ingestion

// Sequential adds: ~30 seconds for 1000 docs
for (let i = 0; i < 1000; i++) {
  await alchemyst.add(documents[i]);
}

// Async add: ~3 seconds for 1000 docs (10x faster!)
// documents is an array of content
const documents = [];
documents.push({
  content: "files content",
  metadata: { // optional
    file_name: "file_name",
    file_type: "pdf/txt/json",
    group_name: ["group1", "group2"],
  },
});

await alchemyst.add(documents);

• Document size > 50MB (max file size - 50MB)
• Large number of documents uploaded sequentially
• Token limit reached

1. Make sure the doc size is less then 50MB
2. Upload documents via bulkAdd (faster)
3. Check if you have sufficent tokens
4. For bulk operations read here

​

Slow Searches (> 1 second)

// Measure your query time
const start = Date.now();
const result = await alchemyst.v1.context.search({
  groupName: ["a", "b", "c", "d", "e", "f", "g"] // 7 filters!
});
console.log(`Search took ${Date.now() - start}ms`);

• 7+ groupName tags (exponential overhead)
• No minimum_similarity_threshold set
• 10K+ documents in scope

1. Reduce to 3-5 groupName tags max
2. Set minimum_similarity_threshold: 0.5
3. Use namespaces to shard data

​

Retrieval Quality Issues

​

No Results Returned

// 1. Verify documents exist
const docs = await alchemyst.v1.context.view();
console.log(`Total docs: ${docs.length}`);

// 2. Try broader search
const result = await alchemyst.v1.context.search({
  query: "your query",
  similarity_threshold: 0.5, // Lower threshold
  groupName: ["broad_tag"] // Fewer filters
});

• High minimum_similarity_threshold set
• groupnames don’t intersect
• Query is not relevant or very specific

1. Verify documents exist : platform
2. Reduce similarity_threshold from 0.6-0.7 to 0.5-0.6
3. Remove overly specific groupNames
4. Try with a general query, make sure it’s not too specific

​

Common Scenarios

​

Scenario: Queries Return Too Many Fragments

• Problem: Search returns 50+ small chunks
• Cause: Over-segmentation (see Anti-Pattern 1)
• Solution: Combine related content into cohesive documents

​

Scenario : Metadata Bloat Symptoms

• Problem: Storing too much or redundant information in metadata
• Cause: Metadata bloating (see Anti-Pattern 2)
• Solution: Limit metadata to only what you query/filter by, pass all the other things in the content itself.

​

Debugging Tools

• Context traces API or Platform
• Verbose SDK logging
• Health check endpoints

​

Platform Limits

​

Still Stuck?

• Check our Discord for community help