brainy/docs/troubleshooting.md

🚨 Troubleshooting Guide

Common issues and solutions for Brainy.

🤖 Model Loading Issues

"Failed to initialize Candle Embedding Engine"

Symptoms: Error during brain.init() with WASM loading failure.

Causes & Solutions:

1. WASM file missing

   # Verify WASM exists (~90MB with embedded model)
   ls -lh dist/embeddings/wasm/pkg/candle_embeddings_bg.wasm
   
   # Rebuild if missing
   npm run build
   

2. Memory too low

   # Ensure at least 256MB available
   # For Docker:
   docker run -m 512m my-app
   

3. Corrupted WASM

   # Rebuild the Candle WASM
   npm run build:candle
   npm run build
   

Slow Initialization (>500ms)

Symptoms: Long wait times during first brain.init().

Cause: WASM parsing takes ~200ms, which is normal for the 90MB file.

Solutions:

// Initialize once at startup, not per-request
await brain.init()  // Do this once

// Reuse for all requests
const results = await brain.find(query)

Container Out of Memory During Model Load

Symptoms: OOM errors in Docker/Kubernetes during initialization.

Solutions:

# Increase memory limit
docker run -m 2g my-app

# Pre-download models at build time (recommended)
RUN npm run download-models

# Use quantized models (default, but explicit)
ENV BRAINY_MODEL_DTYPE=q8

💾 Storage Issues

Permission Denied Creating Storage Directory

Symptoms: EACCES or permission errors when creating storage files.

Solutions:

# Make directory writable
chmod 755 ./brainy-data

# Use custom writable path
const brain = new Brainy({
  storage: {
    type: 'filesystem',
    path: '/tmp/brainy-data'
  }
})

"ENOENT: no such file or directory"

Symptoms: File not found errors during storage operations.

Solutions:

# Ensure parent directory exists
mkdir -p ./brainy-data

# Check storage configuration
const brain = new Brainy({
  storage: {
    type: 'filesystem',
    path: '/full/path/to/storage' // Use absolute path
  }
})

🧠 Initialization Issues

Initialization Hangs or Times Out

Symptoms: brain.init() never resolves.

Possible Causes & Solutions:

1. Model download timeout

   # Pre-download models
   npm run download-models
   
   # Or force local-only
   export BRAINY_ALLOW_REMOTE_MODELS=false
   

2. Network issues

   // Set initialization timeout
   const brain = new Brainy()
   
   // Use Promise.race for timeout
   const initPromise = Promise.race([
     brain.init(),
     new Promise((_, reject) => 
       setTimeout(() => reject(new Error('Init timeout')), 30000)
     )
   ])
   

3. Resource constraints

   # Increase memory for Node.js
   NODE_OPTIONS="--max-old-space-size=4096" npm start
   

🔍 Search Issues

No Search Results

Symptoms: Empty results from valid queries.

Debugging Steps:

1. Check if data exists

   const stats = await brain.getStats()
   console.log(`Total items: ${stats.nounCount}`)
   

2. Verify embedding generation

   const id = await brain.add("test content", { nounType: 'content' })
   const item = await brain.get(id)
   console.log('Item:', item) // Should have metadata and vector
   

3. Test with exact match

   const results = await brain.find("test content") // Exact text
   console.log('Exact match results:', results)
   

Poor Search Quality

Symptoms: Irrelevant results, low scores.

Improvements:

1. Add more context to queries

   // Instead of: "cat"
   const results = await brain.find("domestic cat animal pet")
   

2. Use metadata filtering

   const results = await brain.find({
     query: "animals",
     where: { category: "pets" },
     limit: 10
   })
   

3. Check data quality

   // Ensure consistent, descriptive content
   await brain.add("Domestic cat - small carnivorous mammal", {
     nounType: 'content',
     category: "animals",
     subcategory: "pets"
   })
   

⚡ Performance Issues

Slow Search Performance

Symptoms: High search latency.

Optimizations:

1. Enable search cache

   const brain = new Brainy({
     cache: {
       search: {
         maxSize: 1000,
         ttl: 300000 // 5 minutes
       }
     }
   })
   

2. Use appropriate limits

   // Don't fetch more than needed
   const results = await brain.find({ query: "query", limit: 10 })
   

3. Consider metadata filtering first

   // Filter by metadata first, then semantic search
   const results = await brain.find({
     query: "query",
     where: { category: "specific" }, // Reduces search space
     limit: 10
   })
   

High Memory Usage

Symptoms: Increasing memory consumption over time.

Solutions:

1. Cleanup when done

   await brain.cleanup() // Releases resources
   

2. Use streaming for large datasets

   // Process in batches instead of loading all at once
   for (let i = 0; i < data.length; i += 100) {
     const batch = data.slice(i, i + 100)
     await Promise.all(batch.map(item => brain.add(item, { nounType: 'content' })))
   }
   

3. Configure memory limits

   NODE_OPTIONS="--max-old-space-size=2048" npm start
   

🧪 Testing Issues

Tests Fail in CI/CD

Symptoms: Tests pass locally but fail in automated environments.

Solutions:

1. Pre-download models in CI

   # .github/workflows/test.yml
   - name: Download Models
     run: npm run download-models
   
   - name: Test with Local Models
     env:
       BRAINY_ALLOW_REMOTE_MODELS: false
     run: npm test
   

2. Use temporary filesystem storage in tests

   // In test setup
   const brain = new Brainy({
     storage: { type: 'filesystem', path: '/tmp/brainy-test' }
   })
   

3. Increase timeout for CI

   // In test files
   describe('Brainy tests', () => {
     it('should work', async () => {
       // Test code
     }, { timeout: 30000 }) // 30 second timeout
   })
   

📋 Environment-Specific Issues

Browser CORS Errors

Symptoms: Model loading fails in browser due to CORS.

Solutions:

// Brainy handles CORS automatically via CDN
// No action needed - models load from CORS-enabled mirrors

// If using custom model URLs, ensure CORS headers:
// Access-Control-Allow-Origin: *

Serverless Cold Start Timeouts

Symptoms: Lambda/Vercel functions timeout during initialization.

Solutions:

# Pre-bundle models in deployment
RUN npm run download-models

# Set environment variables
ENV BRAINY_ALLOW_REMOTE_MODELS=false
ENV BRAINY_MODELS_PATH=./models

Node.js Module Resolution Issues

Symptoms: "Cannot find module" errors.

Solutions:

// package.json
{
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.js"
    }
  }
}

🆘 Getting Help

Debug Logging

Enable verbose logging to see what's happening:

const brain = new Brainy({
  logging: { verbose: true }
})

Health Check

Verify your Brainy setup:

// Basic health check
try {
  const brain = new Brainy()
  await brain.init()
  
  const id = await brain.add("health check", { nounType: 'content' })
  const results = await brain.find("health")
  
  console.log('✅ Brainy is working correctly')
  console.log(`Added item: ${id}`)
  console.log(`Search results: ${results.length}`)
  
} catch (error) {
  console.error('❌ Brainy health check failed:', error)
}

Environment Info

Collect environment information:

# Node.js version
node --version

# Memory limits
node -e "console.log(process.memoryUsage())"

# Platform info
node -e "console.log(process.platform, process.arch)"

# Verify WASM file exists (model embedded inside)
ls -la dist/embeddings/wasm/pkg/candle_embeddings_bg.wasm

Report Issues

When reporting issues, include:

1. Environment: Node.js version, OS, memory
2. Configuration: Brainy options, environment variables
3. Error logs: Full error messages and stack traces
4. Reproduction: Minimal code example that demonstrates the issue

Where to report:

• GitHub Issues
• Include "troubleshooting" label
• Use the issue template

---

Still having issues? Check the Model Loading Guide or open an issue.