Troubleshooting

Troubleshooting Guide

Common issues and solutions for Context Processor.

Installation Issues

"Cannot find module 'context-processor'"

Solutions:

1. Clear npm cache:

   npm cache clean --force
   npm install context-processor

2. Check Node version (requires 16.0.0+):

   node --version

3. Reinstall:

   rm -rf node_modules package-lock.json
   npm install

---

Runtime Issues

TypeError: Cannot read property 'save' of undefined

Solution: Initialize the processor:

import { ContextProcessor } from "context-processor";
const processor = new ContextProcessor();

---

ENOENT: no such file or directory

Solutions:

1. Create contexts directory:

   mkdir -p ./contexts

2. Check permissions:

   chmod 755 ./contexts

3. Check disk space:

   df -h

---

Search Issues

Search returns empty results

Solutions:

1. Verify contexts exist:

   const all = processor.list();
   console.log("Total:", all.length);

2. Check tag exact match (tags are case-sensitive):

   processor.search({ tags: ["react"] }); // lowercase

3. Remember AND logic for multiple tags:

   processor.search({ tags: ["react", "hooks"] }); 
   // Returns only contexts with BOTH tags

---

Performance Issues

Slow operations

Solutions:

1. Process in batches:

   for (let i = 0; i < items.length; i += 100) {
     const batch = items.slice(i, i + 100);
     batch.forEach(item => processor.save(item));
     await delay(100);
   }

2. Use simpler models:

   processor.save(data, "clarify"); // Faster than comprehensive

3. Use pagination:

   processor.list({ limit: 100, offset: 0 });

---

High memory usage

Solutions:

1. Process incrementally, not all at once

2. Clear old contexts regularly:

   const old = processor.list()
     .filter(c => Date.now() - c.updatedAt > 30 * 24 * 60 * 60 * 1000);
   old.forEach(c => processor.delete(c.id));

3. Increase Node memory:

   node --max-old-space-size=4096 app.js

---

Processing Issues

Model not applied

Solutions:

1. Verify model exists:

   const models = processor.listModels();
   console.log(models.map(m => m.name));

2. Check model info:

   const info = processor.getModelInfo("comprehensive");
   console.log(info.strategies);

---

Clarity score seems wrong

Note: Clarity scoring is algorithmic and serves as a guideline. Review the suggestions instead of relying solely on the score.

---

Windows-Specific Issues

"ENOTEMPTY" or "Directory not empty" errors

Solution: This is fixed in v1.0.1+ with sequential test execution. Ensure you have the latest version:

npm install context-processor@latest

---

Getting Help

Before opening an issue:

1. Check this troubleshooting guide
2. Review the FAQ
3. Gather error details and system info:

   node --version
   npm --version
   npm list context-processor

Open an issue with:

1. What you were trying to do
2. Exact error message
3. Steps to reproduce
4. System info (OS, Node version)
5. Code snippet if possible

---

Performance Tips

General Optimization

1. Batch operations - Process groups of items together
2. Pagination - Use limit/offset for large lists
3. Minimize preprocessing - Use specific models, not always comprehensive
4. Monitor memory - Watch RAM usage with large datasets

---

Still need help? Open a GitHub Issue or join Community Testing!