Troubleshooting

​

Installation Issues

​

Error: Cannot find module ‘context-window’

# Install the package
npm install context-window

# or with pnpm
pnpm install context-window

# Verify installation
npm list context-window

​

TypeScript errors after installation

# Ensure TypeScript is installed
npm install --save-dev typescript

# Update to latest version
npm install context-window@latest

# Clean and rebuild
rm -rf node_modules package-lock.json
npm install

​

API Key Issues

​

Error: “Invalid API key” (OpenAI)

• Error message contains “Invalid API key”
• 401 Unauthorized responses

echo $OPENAI_API_KEY
# Should output: sk-...

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Good
OPENAI_API_KEY=sk-abc123...

# Bad
OPENAI_API_KEY="sk-abc123..."  # Remove quotes
OPENAI_API_KEY= sk-abc123...   # No space after =

console.log("API key loaded:",
  process.env.OPENAI_API_KEY ? "Yes" : "No"
);

// Make sure you're loading .env
import "dotenv/config";

​

Error: “Invalid API key” (Pinecone)

1. Verify key in Pinecone Console:
   • Go to app.pinecone.io
   • Navigate to API Keys
   • Copy the correct key
2. Check environment variable:
   Copy

   echo $PINECONE_API_KEY
   
3. Test connection:
   Copy

   import { Pinecone } from "@pinecone-database/pinecone";
   
   const pinecone = new Pinecone({
     apiKey: process.env.PINECONE_API_KEY || ""
   });
   
   const indexes = await pinecone.listIndexes();
   console.log("Indexes:", indexes);
   

​

Pinecone Issues

​

Error: “Index not found”

• “Index ‘xyz’ not found”
• Cannot connect to Pinecone index

# In .env
PINECONE_INDEX=context-window

# In code
namespace: "context-window"  # Must match

​

Error: “Incorrect dimensions”

• “Dimension mismatch: expected X, got 1536”
• Embedding dimension errors

​

Error: “Rate limit exceeded” (Pinecone)

// Add retry logic with exponential backoff
async function upsertWithRetry(index, vectors, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await index.upsert(vectors);
      return;
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Reduce batch sizes
// Process fewer documents at once

​

Ingestion Problems

​

Documents not found

• “ENOENT: no such file or directory”
• Files not being ingested

// If running from project root:
data: ["./docs"]  // ✓

// Not from where the code file is located
data: ["../docs"]  // Might be wrong

import path from "path";
data: [path.join(__dirname, "docs")]

# List files in directory
ls -la ./docs

# Check specific file
ls -l ./document.pdf

# Make sure files are readable
chmod +r ./docs/*

​

PDF parsing fails

• Error: “Failed to parse PDF”
• Empty content from PDF files

# Try opening with pdftoppm
pdftoppm -png file.pdf test

# Increase Node.js memory
NODE_OPTIONS=--max-old-space-size=4096 node script.js

​

Ingestion is very slow

• Takes many minutes to ingest documents
• Seems stuck during ingestion

// Reduce number of chunks
chunk: { size: 2000, overlap: 100 }

// Process in batches
for (const batch of batches) {
  await createCtxWindow({ data: batch, /* ... */ });
}

​

Query Issues

​

Always returns “I don’t know”

• Every question returns “I don’t know based on the uploaded files”
• No relevant answers found

limits: {
  scoreThreshold: 0  // Remove filtering
}

limits: {
  topK: 12,               // More chunks
  maxContextChars: 12000  // More context
}

// If docs say "authentication"
✓ "How does authentication work?"
✗ "How do I log in?"

// Creation
vectorStore: { namespace: "docs-v1" }

// Query - must use same namespace
// If using registry, namespace should match

​

Inconsistent or wrong answers

• Answers change between identical questions
• Answers don’t match document content
• Contradictory information

limits: {
  topK: 10  // Retrieve more relevant chunks
}

chunk: {
  size: 1500,   // Larger chunks
  overlap: 250  // More overlap
}

ai: {
  provider: "openai",
  model: "gpt-4o"  // More accurate than gpt-4o-mini
}

​

Slow response times

• Questions take more than 5 seconds
• Timeout errors

// 1. Use faster model
ai: { provider: "openai", model: "gpt-4o-mini" }

// 2. Reduce context
limits: {
  topK: 5,
  maxContextChars: 5000
}

// 3. Add timeout handling
async function askWithTimeout(cw, question, ms = 10000) {
  return Promise.race([
    cw.ask(question),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error("Timeout")), ms)
    )
  ]);
}

// 4. Implement caching
const cache = new Map();
if (cache.has(question)) return cache.get(question);

​

Memory Issues

​

Out of memory during ingestion

• “JavaScript heap out of memory”
• Process crashes during ingestion

# Set higher memory limit
NODE_OPTIONS=--max-old-space-size=4096 node script.js

# Or in package.json scripts
{
  "scripts": {
    "start": "NODE_OPTIONS=--max-old-space-size=4096 node index.js"
  }
}

// Instead of all at once:
data: ["./all-docs"]

// Do in batches:
await createCtxWindow({
  namespace: "batch-1",
  data: ["./docs/part1"]
});

await createCtxWindow({
  namespace: "batch-2",
  data: ["./docs/part2"]
});

chunk: { size: 2000, overlap: 200 }

​

Runtime Errors

​

Error: “Context window not found”

import { hasCtxWindow, createCtxWindow, getCtxWindow } from "context-window";

// Check before retrieving
if (!hasCtxWindow("my-docs")) {
  await createCtxWindow({
    namespace: "my-docs",
    data: ["./docs"],
    ai: { provider: "openai" },
    vectorStore: { provider: "pinecone" }
  });
}

const cw = getCtxWindow("my-docs");

​

Error: “Rate limit exceeded” (OpenAI)

• “Rate limit reached for requests”
• 429 status code

async function askWithRetry(cw, question, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await cw.ask(question);
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      // Exponential backoff
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

limits: {
  topK: 5,               // Fewer chunks
  maxContextChars: 5000  // Less context
}

​

Network errors

• “ECONNREFUSED”
• “Network request failed”
• Timeout errors

1. Check internet connection
2. Verify firewall settings (ports 443 for HTTPS)
3. Check proxy settings if behind corporate proxy:
   Copy

   export HTTP_PROXY=http://proxy:port
   export HTTPS_PROXY=http://proxy:port
   
4. Retry with exponential backoff (see above)

​

Environment Issues

​

.env file not loaded

• Environment variables are undefined
• “API key not set” errors

// Install dotenv
npm install dotenv

// Load at the TOP of your entry file
import "dotenv/config";
// or
import dotenv from "dotenv";
dotenv.config();

// Verify loading
console.log("OPENAI_API_KEY:", process.env.OPENAI_API_KEY ? "Loaded" : "Missing");

​

Different behavior in production

import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const docsPath = path.join(__dirname, "docs");

​

Still Stuck?

• Node.js version (node --version)
• Package version (npm list context-window)
• Error message and stack trace
• Minimal code to reproduce the issue
• Operating system