learningcircuit--local-deep-research/docs/troubleshooting-openai-api-key.md

Troubleshooting OpenAI API Key Configuration

This guide helps troubleshoot common issues with OpenAI API key configuration in Local Deep Research v1.0+.

Quick Test

Run the end-to-end test to verify your configuration:

# Using command line arguments
python tests/test_openai_api_key_e2e.py \
  --username YOUR_USERNAME \
  --password YOUR_PASSWORD \
  --api-key YOUR_OPENAI_API_KEY

# Using environment variables
export LDR_USERNAME=your_username
export LDR_PASSWORD=your_password
export OPENAI_API_KEY=sk-your-api-key
python tests/test_openai_api_key_e2e.py

Common Issues and Solutions

1. "No API key found"

Symptoms:

• Error message about missing API key
• Research fails to start

Solutions:

1. Via Web Interface:

   • Login to LDR web interface
   • Go to Settings
   • Select "OpenAI" as LLM Provider
   • Enter your API key in the "OpenAI API Key" field
   • Click Save

2. Via Environment Variable:

   export OPENAI_API_KEY=sk-your-api-key
   python -m local_deep_research.web.app
   

3. Programmatically:

   from local_deep_research.settings import SettingsManager
   from local_deep_research.database.session_context import get_user_db_session
   
   with get_user_db_session(username="user", password="pass") as session:
       settings_manager = SettingsManager(session)
       settings_manager.set_setting("llm.provider", "openai")
       settings_manager.set_setting("llm.openai.api_key", "sk-your-api-key")
   

2. "Invalid API key"

Symptoms:

• 401 Unauthorized errors
• "Incorrect API key provided" messages

Solutions:

1. Verify API Key Format:

   • OpenAI keys start with sk-
   • Should be around 51 characters long
   • No extra spaces or quotes

2. Check API Key Validity:

   # Test directly with curl
   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer YOUR_API_KEY"
   

3. Regenerate API Key:

   • Go to https://platform.openai.com/api-keys
   • Create a new API key
   • Update in LDR settings

3. "Rate limit exceeded"

Symptoms:

• 429 errors
• "You exceeded your current quota" messages

Solutions:

1. Check OpenAI Usage:

   • Visit https://platform.openai.com/usage
   • Verify you have available credits

2. Add Payment Method:

   • OpenAI requires payment info for API access
   • Add at https://platform.openai.com/account/billing

3. Use Different Model:

   settings_manager.set_setting("llm.model", "gpt-3.5-turbo")  # Cheaper
   # Instead of gpt-4 which is more expensive
   

4. "Settings not persisting"

Symptoms:

• API key needs to be re-entered after restart
• Settings revert to defaults

Solutions:

1. Ensure Proper Shutdown:

   • Use Ctrl+C to stop server (not kill -9)
   • Wait for "Server stopped" message

2. Check Database Permissions:

   ls -la encrypted_databases/
   # Should show your user database with write permissions
   

3. Verify Settings Save:

   # After setting, verify it was saved
   saved_key = settings_manager.get_setting("llm.openai.api_key")
   print(f"Saved key: {'*' * 20 if saved_key else 'Not saved'}")
   

5. "API key not being used"

Symptoms:

• Settings show OpenAI configured but different LLM is used
• API key is saved but not applied

Solutions:

1. Check Provider Setting:

   provider = settings_manager.get_setting("llm.provider")
   print(f"Current provider: {provider}")  # Should be "openai"
   

2. Verify Settings Snapshot:

   settings_snapshot = settings_manager.get_all_settings()
   print("Provider:", settings_snapshot.get("llm.provider", {}).get("value"))
   print("API Key:", "Set" if settings_snapshot.get("llm.openai.api_key", {}).get("value") else "Not set")
   

3. Force Provider Selection:

   # In research call
   result = quick_summary(
       query="Test",
       settings_snapshot=settings_snapshot,
       provider="openai",  # Force OpenAI
       model_name="gpt-3.5-turbo"
   )
   

Testing Your Configuration

1. Simple API Test

from local_deep_research.config.llm_config import get_llm
from local_deep_research.settings import SettingsManager
from local_deep_research.database.session_context import get_user_db_session

with get_user_db_session(username="user", password="pass") as session:
    settings_manager = SettingsManager(session)
    settings_snapshot = settings_manager.get_all_settings()

    # Test LLM initialization
    try:
        llm = get_llm(settings_snapshot=settings_snapshot)
        print("✓ LLM initialized successfully")

        # Test response
        from langchain.schema import HumanMessage
        response = llm.invoke([HumanMessage(content="Say hello")])
        print(f"✓ Response: {response.content}")
    except Exception as e:
        print(f"✗ Error: {e}")

2. Full Research Test

from local_deep_research.api.research_functions import quick_summary

result = quick_summary(
    query="What is OpenAI?",
    settings_snapshot=settings_snapshot,
    iterations=1,
    questions_per_iteration=1
)

print(f"Research ID: {result['research_id']}")
print(f"Summary: {result['summary'][:200]}...")

Advanced Configuration

Using Azure OpenAI

settings_manager.set_setting("llm.provider", "openai")
settings_manager.set_setting("llm.openai.api_key", "your-azure-key")
settings_manager.set_setting("llm.openai.api_base", "https://your-resource.openai.azure.com/")
settings_manager.set_setting("llm.model", "your-deployment-name")

Using OpenAI-Compatible Endpoints

settings_manager.set_setting("llm.provider", "openai")
settings_manager.set_setting("llm.openai.api_key", "your-api-key")
settings_manager.set_setting("llm.openai.api_base", "https://your-endpoint.com/v1")

Organization ID

settings_manager.set_setting("llm.openai.organization", "org-your-org-id")

Getting Help

1. Run Diagnostic Test:

   python tests/test_openai_api_key_e2e.py --verbose
   

2. Check Logs:

   # Look for OpenAI-related errors
   grep -i "openai\|api.*key" logs/ldr.log
   

3. Community Support:

   • GitHub Issues: https://github.com/LearningCircuit/local-deep-research/issues
   • Discord: https://discord.gg/ttcqQeFcJ3

4. API Key Best Practices:

   • Never commit API keys to version control
   • Use environment variables for production
   • Rotate keys regularly
   • Set usage limits in OpenAI dashboard

See Also

• Full Configuration Reference - All settings, defaults, and environment variables
• Configuration Guide - Environment variable setup guide
• Troubleshooting - General troubleshooting