Debug Recipes

Step-by-step guide to debugging and troubleshooting recipes

Run validation and verbose recipe commands when a template fails in production.

from praisonaiagents import Agent

agent = Agent(name="Recipe Debugger", instructions="Explain recipe validation errors clearly.")
agent.start("Why did my recipe fail tool resolution?")

The user enables verbose mode, validates the recipe folder, and fixes configuration before re-running.

How It Works

---

How to Debug Recipe Execution

1. Enable Verbose Mode

   praisonai recipe run my-recipe --verbose
   
2. Check Recipe Validation

   praisonai recipe validate ./my-recipe
   
3. View Recipe Info

   praisonai recipe info my-recipe
   
4. Check Tool Resolution

   praisonai tools list
   

How to Use Recipe Doctor

1. Run Doctor Command

   praisonai tools doctor
   
2. Review Diagnostics

   The doctor command will show:

   • Missing tools
   • Invalid tool references
   • Configuration issues
   • Dependency problems
3. Fix Issues

   Based on doctor output, fix the identified issues in your recipe files.

How to Debug Tool Resolution

When loading a template, PraisonAI now asks the full ToolResolver whether each referenced tool exists — not just the built-in TOOL_MAPPINGS. As of PR #2642, templates that reference tools registered via praisonai_tools, register_function, or entry-point plugins load without spurious “missing / needs install” warnings.

1. List Available Tools

   praisonai tools list
   
2. Resolve Specific Tool

   praisonai tools resolve shell_tool
   

How to Debug with Python

1. Enable Debug Logging

   import logging
   logging.basicConfig(level=logging.DEBUG)
   
   from praisonaiagents import Agent
   
   agent = Agent(
       name="test",
       role="Test Agent",
       verbose=True
   )
   
2. Test Agent Execution

   result = agent.start("Test task")
   print(result)
   

Common Issues and Solutions

Issue	Cause	Solution
Tool not found	Tool not available	Check praisonai tools list
Variable undefined	Missing variable	Pass with --var key=value
Recipe not found	Wrong path	Use full path
Permission denied	File access	Check file permissions

Debug CLI Options

praisonai recipe run <recipe> [DEBUG OPTIONS]

Debug Options:
  --verbose              Enable verbose logging

Best Practices

Validate first, then run verbose

praisonai recipe validate catches structural errors cheaply; reach for --verbose only when a valid recipe still misbehaves at run time.

Confirm tools resolve before blaming the recipe

praisonai tools list and praisonai tools resolve <name> show whether a referenced tool is actually available, which is the most common recipe failure.

Reproduce failures with debug logging in Python

Set logging.basicConfig(level=logging.DEBUG) and verbose=True on the agent to surface the exact step that fails.

---

Related

Add Tools to Recipes

Fix tool resolution issues

Manage Recipes

Update and edit recipes