> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Troubleshooting guide for common problems

## API Client Not Configured

```
Error: Runflow API Client is not configured
```

**Solution:** Ensure you have either:

1. Environment variables set (`RUNFLOW_API_KEY`, `RUNFLOW_TENANT_ID`)
2. A `.runflow/rf.json` file
3. Manually configured the API client

```typescript theme={null}
import { createRunflowAPIClient, Agent, openai } from '@runflow-ai/sdk';

const apiClient = createRunflowAPIClient({
  apiKey: 'your_api_key',
  tenantId: 'your_tenant_id',
});

const agent = new Agent({
  name: 'My Agent',
  instructions: 'Help users',
  model: openai('gpt-4o'),
});

agent._setAPIClient(apiClient);
```

## Memory Not Persisting

**Issue:** Memory is not persisting between sessions

**Solution:** Ensure you're passing the same `sessionId` or using `identify()` consistently:

```typescript theme={null}
import { identify } from '@runflow-ai/sdk/observability';

// Use identify() for automatic session management
identify('+5511999999999');

// OR pass sessionId explicitly
await agent.process({
  message: 'Hello',
  sessionId: 'session_456', // Same session ID
});
```

## Tool Not Being Called

**Issue:** Agent is not calling tools even when it should

**Solution:**

1. Make sure tool descriptions are clear and specific
2. Use `debug: true` to see what the agent is doing
3. Check that `maxToolIterations` is not set too low

```typescript theme={null}
const agent = new Agent({
  name: 'My Agent',
  instructions: 'You MUST use the weather tool when users ask about weather.',
  model: openai('gpt-4o'),
  tools: {
    weather: weatherTool,
  },
  maxToolIterations: 10, // Default
  debug: true, // Enable debug logging
});
```

## RAG Not Finding Results

**Issue:** Knowledge base search returns no results

**Solution:**

1. Check `threshold` value (lower = more results)
2. Increase `k` value for more results
3. Verify vector store name is correct

```typescript theme={null}
rag: {
  vectorStore: 'support-docs', // Verify this exists
  k: 10,           // Increase for more results
  threshold: 0.5,  // Lower for more lenient matching
}
```

## TypeScript Errors

**Issue:** TypeScript errors when using the SDK

**Solution:** Make sure you're using TypeScript >= 5.0.0 and have proper types:

```bash theme={null}
npm install --save-dev typescript@^5.0.0
```

```typescript theme={null}
// Use proper type imports
import type { AgentConfig, AgentInput, AgentOutput } from '@runflow-ai/sdk';
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/config-file">
    Review configuration
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Check API documentation
  </Card>
</CardGroup>