Troubleshooting

​

Installation issues

​

pip install langchat fails

# Upgrade pip first
pip install --upgrade pip
pip install langchat

# Or use uv
uv pip install langchat

​

Python version error

python --version

​

API key errors

​

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

# Option 1: .env file (recommended)
echo "OPENAI_API_KEY=sk-..." >> .env

# Option 2: load .env explicitly
from langchat import LangChat
LangChat.load_env()

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

​

Same error for Pinecone / Supabase

​

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
3. Check PINECONE_API_KEY is set and valid

from langchat.providers import Pinecone
vector_db = Pinecone("my-exact-index-name")

​

Dimension mismatch error

​

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

​

Row Level Security policy violation

SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...  # use this instead of SUPABASE_KEY

​

Chat issues

​

Empty or very short responses

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

prompt = """Answer questions using this context:
{context}

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

​

Conversation history not working

# ✓ 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'

pip install langchat
# Verify you're in the correct virtual environment
which python

​

ImportError when importing a provider

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
3. Open a new issue with your error message, Python version, and minimal reproduction