Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
Agent Recipes Troubleshooting
Common issues and solutions when working with Agent Recipes.
Diagnostic Commands
Check All Dependencies
# Check specific recipe
praison recipes doctor ai-subtitle-generator
# Example output:
# Checking dependencies for: ai-subtitle-generator
# --------------------------------------------------
# ✓ env:OPENAI_API_KEY
# ✓ package:openai
# ✗ external:ffmpeg
# ✗ tool:whisper_tool
# --------------------------------------------------
# Missing dependencies. Install with:
# brew install ffmpeg # macOS
# apt install ffmpeg # Ubuntu
Verify API Keys
# Test LLM connectivity
python3 -c "
import os
os.environ['OPENAI_API_KEY'] = 'your-key'
from praisonai_tools.recipe_tools import LLMTool
llm = LLMTool(provider='openai')
print(llm.check_dependencies())
response = llm.complete('Say hello', max_tokens=10)
print(f'Success: {response.content}')
"
List Available Recipes
praison recipes list --json | python3 -c "
import json, sys
recipes = json.load(sys.stdin)
print(f'Total recipes: {len(recipes)}')
for r in recipes[:5]:
print(f\" - {r['name']}: {r['description'][:50]}...\")
"
Common Issues
1. Missing API Key
Error:
DependencyError: OPENAI_API_KEY not set
Solution:
# Set environment variable
export OPENAI_API_KEY=sk-proj-...
# Or in Python
import os
os.environ['OPENAI_API_KEY'] = 'sk-proj-...'
# Verify
echo $OPENAI_API_KEY | tail -c 5 # Shows last 4 chars
Error:
✗ external:ffmpeg
FileNotFoundError: ffmpeg not found
Solution:
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# Windows (with chocolatey)
choco install ffmpeg
# Verify
ffmpeg -version
Error:
Solution:
# macOS
brew install tesseract
# Ubuntu/Debian
sudo apt install tesseract-ocr
# Verify
tesseract --version
4. Missing Python Package
Error:
✗ package:openai
ModuleNotFoundError: No module named 'openai'
Solution:
# Install specific package
pip install openai
# Install all recipe tools
pip install praisonai-tools[all]
# Install cluster-specific extras
pip install praisonai-tools[media] # Video/audio
pip install praisonai-tools[image] # Image processing
pip install praisonai-tools[docs] # Document processing
5. API Rate Limit
Error:
RateLimitError: Rate limit exceeded
Solution:
import time
from praisonai_tools.recipe_tools import LLMTool
llm = LLMTool(provider="openai")
def complete_with_retry(prompt, max_retries=3):
for attempt in range(max_retries):
try:
return llm.complete(prompt)
except Exception as e:
if "rate_limit" in str(e).lower():
wait = 2 ** attempt # Exponential backoff
print(f"Rate limited, waiting {wait}s...")
time.sleep(wait)
else:
raise
raise Exception("Max retries exceeded")
6. Invalid Model Name
Error:
InvalidRequestError: The model 'gpt-5' does not exist
Solution:
# Use valid model names
from praisonai_tools.recipe_tools import LLMTool
# OpenAI models
llm = LLMTool(provider="openai", model="gpt-4o-mini") # ✓
llm = LLMTool(provider="openai", model="gpt-4o") # ✓
llm = LLMTool(provider="openai", model="gpt-4-turbo") # ✓
# Anthropic models
llm = LLMTool(provider="anthropic", model="claude-3-haiku-20240307") # ✓
llm = LLMTool(provider="anthropic", model="claude-3-sonnet-20240229") # ✓
# Google models
llm = LLMTool(provider="google", model="gemini-1.5-flash") # ✓
llm = LLMTool(provider="google", model="gemini-1.5-pro") # ✓
7. Recipe Not Found
Error:
Recipe not found: ai-custom-recipe
Solution:
# List available recipes
praison recipes list | grep -i "custom"
# Check recipe paths
ls ~/.praisonai/templates/
ls ~/.config/praison/templates/
ls /Users/praison/Agent-Recipes/agent_recipes/templates/
# Initialize a recipe locally
praison recipes init ai-blog-generator --output ./my-recipe
8. Permission Denied
Error:
PermissionError: [Errno 13] Permission denied: '/output/file.txt'
Solution:
# Check directory permissions
ls -la ./output/
# Create output directory with proper permissions
mkdir -p ./output
chmod 755 ./output
# Or specify writable output path
praison recipes run ai-blog-generator --output ~/Documents/output/
9. Memory Error with Large Files
Error:
MemoryError: Unable to allocate array
Solution:
# Process large files in chunks
import pandas as pd
# Instead of loading entire file
# df = pd.read_csv("large_file.csv") # ✗
# Use chunked processing
chunks = pd.read_csv("large_file.csv", chunksize=10000)
for chunk in chunks:
# Process each chunk
pass
10. Timeout Error
Error:
TimeoutError: Request timed out after 30 seconds
Solution:
from praisonai_tools.recipe_tools import LLMTool
# Increase timeout
llm = LLMTool(provider="openai", timeout=120)
# Or use streaming for long responses
for chunk in llm.stream("Write a long essay..."):
print(chunk, end="", flush=True)
Debug Mode
Enable Verbose Logging
import logging
# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
# Or for specific module
logging.getLogger("praisonai_tools").setLevel(logging.DEBUG)
Inspect Recipe Configuration
import yaml
def inspect_recipe(name):
"""Print recipe configuration for debugging."""
from pathlib import Path
paths = [
Path.home() / ".praison" / "templates" / name,
Path("/Users/praison/Agent-Recipes/agent_recipes/templates") / name,
]
for path in paths:
template = path / "TEMPLATE.yaml"
if template.exists():
with open(template) as f:
config = yaml.safe_load(f)
print(f"Recipe: {name}")
print(f"Path: {path}")
print(f"Config: {yaml.dump(config, default_flow_style=False)}")
return config
print(f"Recipe not found: {name}")
return None
inspect_recipe("ai-blog-generator")
Getting Help
Check Documentation
# Recipe info
praison recipes info ai-blog-generator
# Recipe explanation
praison recipes explain ai-blog-generator
Report Issues
If you encounter a bug:
- Check existing issues: GitHub Issues
- Include:
- Recipe name and version
- Full error message
- Python version (
python --version)
- OS and version
- Steps to reproduce
Next Steps