Skip to main content

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

2. Missing External Tool (ffmpeg)

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

3. Missing External Tool (tesseract)

Error:
✗ external:tesseract
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 ~/.praison/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:
  1. Check existing issues: GitHub Issues
  2. Include:
    • Recipe name and version
    • Full error message
    • Python version (python --version)
    • OS and version
    • Steps to reproduce

Community Support

Next Steps