Back to Documentation
Troubleshooting
Common issues and their solutions. Can't find your answer? Check the CLI doctor command or join our Discord.
npx rana doctor
Quick Diagnostic
Run the doctor command to diagnose common issues:
npx rana doctor
This checks: API keys, dependencies, configuration, and connectivity.
Installation
How do I install RANA?▼
Install all packages at once:
```bash
npm install @rana/core @rana/helpers @rana/prompts @rana/rag
```
Or install the CLI globally:
```bash
npm install -g @rana/cli
```
I get "Module not found" errors after installation▼
Try these steps:
1. Clear your node_modules and reinstall:
```bash
rm -rf node_modules package-lock.json
npm install
```
2. Make sure you're using Node.js 18 or higher:
```bash
node --version
```
3. If using TypeScript, ensure your tsconfig.json has:
```json
{
"compilerOptions": {
"moduleResolution": "node16" // or "bundler"
}
}
```
TypeScript types are not working▼
RANA is fully typed. Make sure you have:
1. TypeScript 5.0 or higher
2. Proper moduleResolution in tsconfig.json
```json
{
"compilerOptions": {
"strict": true,
"moduleResolution": "bundler",
"esModuleInterop": true
}
}
```
API Keys
Where do I put my API keys?▼
Create a `.env` file in your project root:
```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...
```
Make sure to add `.env` to your `.gitignore`!
For production, use your platform's environment variable system (Vercel, Railway, etc.)
I get "Invalid API key" errors▼
1. Check that your API key is correct and hasn't expired
2. Make sure there are no extra spaces or quotes around the key
3. Verify the key is for the correct environment (production vs test)
4. Check your provider's dashboard to ensure the key is active
```bash
# Validate your setup
npx rana doctor
```
How do I use different API keys per environment?▼
Use different .env files:
```
.env.local # Local development
.env.development # Development server
.env.production # Production
```
Or use environment-specific configuration:
```typescript
import { configure } from '@rana/core';
configure({
providers: {
openai: {
apiKey: process.env.NODE_ENV === 'production'
? process.env.OPENAI_API_KEY_PROD
: process.env.OPENAI_API_KEY_DEV
}
}
});
```
Performance
Requests are slow. How can I speed them up?▼
Several strategies:
1. **Use streaming** for faster perceived response:
```typescript
for await (const chunk of agent.stream(message)) {
process.stdout.write(chunk.content);
}
```
2. **Enable caching** for repeated queries:
```typescript
configure({
cache: { enabled: true, ttl: '1h' }
});
```
3. **Use a faster model** for simple tasks:
```typescript
const agent = new Agent({
model: 'claude-3-haiku-20240307' // Faster than Sonnet
});
```
4. **Reduce token count** by shortening prompts
How do I handle rate limits?▼
RANA handles rate limits automatically with retries and backoff.
For additional control:
```typescript
import { RateLimiter } from '@rana/core';
const limiter = new RateLimiter({
requests: { max: 100, window: '1m' }
});
// Check before making request
const allowed = await limiter.checkLimit('requests');
if (!allowed.success) {
await delay(allowed.retryAfter);
}
```
Or configure fallbacks to switch providers when rate limited.
Memory usage is too high▼
1. **Clear conversation memory** periodically:
```typescript
conversation.clear();
```
2. **Use streaming** instead of buffering full responses
3. **Limit conversation history**:
```typescript
const memory = new ConversationMemory({
maxMessages: 20 // Keep only recent messages
});
```
4. **Use compression** for long conversations:
```typescript
const compressor = new MemoryCompressor({
targetTokens: 1000
});
```
Costs
How do I track my AI spending?▼
RANA tracks costs automatically:
```typescript
import { CostTracker } from '@rana/core';
const tracker = new CostTracker();
const result = await tracker.wrap(
() => agent.run(message)
);
console.log(result.cost); // $0.0023
```
Or use the dashboard:
```bash
npx rana dashboard
```
How do I set budget limits?▼
Set hard budget limits to prevent overspending:
```typescript
import { BudgetManager } from '@rana/core';
const budget = new BudgetManager();
await budget.setGlobalBudget({
daily: 100, // $100/day
monthly: 2000 // $2000/month
});
// Per-user budgets
await budget.setUserBudget(userId, {
daily: 5
});
```
How can I reduce costs?▼
1. **Enable caching** - avoid duplicate requests
2. **Use cheaper models** for simple tasks
3. **Compress prompts** - shorter prompts = lower costs
4. **Use model routing** - automatically pick cheapest suitable model
```typescript
import { CostOptimizer } from '@rana/core';
const optimizer = new CostOptimizer({
strategies: ['caching', 'model-routing', 'prompt-compression']
});
const result = await optimizer.optimize(
() => agent.run(message)
);
console.log(result.savings); // "60%"
```
Common Errors
Error: "Request timeout"▼
Increase the timeout or use streaming:
```typescript
// Increase timeout
configure({
timeout: 60000 // 60 seconds
});
// Or use streaming for long responses
for await (const chunk of agent.stream(message)) {
// Process chunks as they arrive
}
```
Error: "Context length exceeded"▼
Your prompt + response exceeds the model's context limit.
Solutions:
1. **Use a model with larger context** (e.g., claude-3 has 200k tokens)
2. **Compress your prompt**:
```typescript
import { compressPrompt } from '@rana/helpers';
const compressed = await compressPrompt(longPrompt);
```
3. **Chunk your input**:
```typescript
import { SemanticChunker } from '@rana/rag';
const chunks = await chunker.chunk(longDocument);
```
Error: "Provider unavailable"▼
The AI provider is temporarily down. RANA can auto-fallback:
```typescript
import { FallbackChain } from '@rana/core';
const chain = new FallbackChain({
providers: [
{ name: 'primary', provider: anthropicClient },
{ name: 'backup', provider: openaiClient }
]
});
// Automatically uses backup if primary fails
const result = await chain.chat({ messages });
```
Error: "Invalid response format"▼
The model didn't return the expected format.
Use structured output to ensure correct format:
```typescript
import { extract } from '@rana/helpers';
const data = await extract(text, {
name: 'string',
age: 'number',
skills: 'string[]'
});
// Guaranteed to match schema
```
Or enable retries on format errors:
```typescript
configure({
retry: {
retryOn: ['format_error'],
maxAttempts: 3
}
});
```