Installation & Setup
Issue: ModuleNotFoundError: No module named 'dspy'
Solution: Install the package using pip install dspy-ai
(not just 'dspy'). Ensure you are in the correct virtual environment.
Issue: Authentication/API Errors
Ensure your API keys are correctly set. For OpenAI:
Python
dspy.configure(api_key="...", model="gpt-4")Or use environment variables like OPENAI_API_KEY.
Runtime Errors
Timeout Errors
Network issues or slow model responses. Try increasing the timeout:
dspy.OpenAI(..., request_timeout=60)Rate Limit Errors
Implement retry logic or backoff. Use the dspy.settings to configure
global retry behavior if available, or wrap calls with retry decorators.
Evaluation & Optimization
Optimization Fails / No Improvement
- Check your metric function logic. It must accurately reflect quality.
- Ensure you have enough high-quality examples in your training set.
- Try a different optimizer (e.g., switch from
BootstrapFewShottoMIPRO).
Debugging Tips
Enable verbose logging to see exactly what is being sent to the LM:
dspy.settings.configure(trace=True)Inspect the last call:
lm.inspect_history(n=1)