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

# Troubleshooting

> Solutions to common LangChat issues.

## Installation issues

### `pip install langchat` fails

```bash theme={null}
# Upgrade pip first
pip install --upgrade pip
pip install langchat

# Or use uv
uv pip install langchat
```

### Python version error

LangChat requires Python 3.9+. Check your version:

```bash theme={null}
python --version
```

If below 3.9, install a newer Python from [python.org](https://python.org) or via `pyenv`.

***

## API key errors

### `ValueError: OpenAI API key is required. Set OPENAI_API_KEY...`

Your API key is not set. Fix with one of:

```bash theme={null}
# Option 1: .env file (recommended)
echo "OPENAI_API_KEY=sk-..." >> .env
```

```python theme={null}
# Option 2: load .env explicitly
from langchat import LangChat
LangChat.load_env()
```

```python theme={null}
# Option 3: pass directly
from langchat.providers import OpenAI
llm = OpenAI("gpt-4o-mini", api_key="sk-...")
```

### Same error for Pinecone / Supabase

Check these environment variables:

| Service   | Variable                             |
| --------- | ------------------------------------ |
| OpenAI    | `OPENAI_API_KEY`                     |
| Anthropic | `ANTHROPIC_API_KEY`                  |
| Gemini    | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
| Mistral   | `MISTRAL_API_KEY`                    |
| Cohere    | `COHERE_API_KEY`                     |
| Pinecone  | `PINECONE_API_KEY`                   |
| Supabase  | `SUPABASE_URL` and `SUPABASE_KEY`    |

***

## Pinecone issues

### `Index not found` or connection error

1. Verify the index name matches exactly (case-sensitive)
2. Confirm the index exists in [app.pinecone.io](https://app.pinecone.io)
3. Check `PINECONE_API_KEY` is set and valid

```python theme={null}
from langchat.providers import Pinecone
vector_db = Pinecone("my-exact-index-name")
```

### `Dimension mismatch` error

Your index dimensions don't match the embedding model. Common cases:

| Model                    | Required dimensions |
| ------------------------ | ------------------- |
| `text-embedding-3-large` | 3072                |
| `text-embedding-3-small` | 1536                |

Create a new index with the correct dimensions or switch embedding models.

### No relevant results / poor answers

1. Verify documents are indexed: check chunk count in your indexing script output
2. Try a more specific query
3. Check `verbose=True` to see what context is being retrieved
4. Increase `top_n` in the reranker (default: 3)

***

## Supabase issues

### Tables not created

Tables are created on first use. If they're missing, run a test `chat()` call or check that `SUPABASE_KEY` has write permissions (use `service_role` key for server-side).

### `Row Level Security policy violation`

Use the `service_role` key instead of the `anon` key:

```bash theme={null}
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...  # use this instead of SUPABASE_KEY
```

***

## Chat issues

### Empty or very short responses

The LLM returned a minimal response. Try:

1. More specific query
2. Verify documents are indexed and relevant
3. Check `verbose=True` to see the full prompt being sent
4. Try a different model (e.g., `gpt-4o` instead of `gpt-4o-mini`)

### Responses ignore context

The prompt template may be misconfigured. Ensure `{context}` appears in your template:

```python theme={null}
prompt = """Answer questions using this context:
{context}

History: {chat_history}
Question: {question}
Answer:"""
```

### Conversation history not working

History is per `user_id` + `platform`. If you're using different values between calls, each call starts fresh:

```python theme={null}
# ✓ Same user_id and platform — maintains history
await lc.chat(query="Hello", user_id="alice", platform="web")
await lc.chat(query="What did I just say?", user_id="alice", platform="web")

# ✗ Different platform — different conversation
await lc.chat(query="Hello", user_id="alice", platform="web")
await lc.chat(query="What did I just say?", user_id="alice", platform="mobile")
```

***

## Performance issues

### Slow response times

1. **Reduce `max_chat_history`** — fewer messages = smaller prompt = faster LLM call
2. **Use a faster model** — `gpt-4o-mini` is \~5× faster than `gpt-4o`
3. **Reduce `top_n` in reranker** — default is 3; try 2
4. **Use `text-embedding-3-small`** instead of `text-embedding-3-large` for Pinecone

### High token costs

1. Use `gpt-4o-mini` instead of `gpt-4o`
2. Reduce `max_chat_history` (each extra exchange costs tokens)
3. Reduce `chunk_size` to keep context chunks shorter
4. Reduce reranker `top_n` to pass fewer chunks to the LLM

***

## Import errors

### `ModuleNotFoundError: No module named 'langchat'`

```bash theme={null}
pip install langchat
# Verify you're in the correct virtual environment
which python
```

### `ImportError` when importing a provider

Some providers have optional dependencies. Install the extras:

```bash theme={null}
pip install langchat
pip install anthropic           # for Anthropic
pip install google-generativeai # for Gemini
pip install mistralai           # for Mistral
pip install cohere              # for Cohere
```

***

## Still stuck?

1. Enable verbose logging: `LangChat(..., verbose=True)`
2. Check the [GitHub Issues](https://github.com/neurobrains/langchat/issues)
3. Open a new issue with your error message, Python version, and minimal reproduction