> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate

> Fail-fast YAML configuration validation with aggregated, actionable errors

Catch configuration mistakes before they cause runtime failures — `praisonai validate` checks your YAML files against the full schema and reports every error at once.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Y["📄 YAML File"] --> S["🔍 Schema Check"]
    S --> X["🔗 Cross-Reference Check"]
    X --> T["🔧 Tool Check"]
    T --> OK["✅ Valid"]
    T --> ERR["❌ Errors"]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef error fill:#EF4444,stroke:#7C90A0,color:#fff

    class Y input
    class S,X,T process
    class OK success
    class ERR error
```

## Quick Start

<Steps>
  <Step title="Validate a single file (success path)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate agents.yaml
    ```

    Output:

    ```
    ✅ agents.yaml is valid
    ```
  </Step>

  <Step title="Validate a file with errors (failure path)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate agents.yaml
    ```

    Output when the config has problems:

    ```
    ❌ agents.yaml is invalid

    Configuration validation failed with 2 error(s):
      1. Agent 'researcher': missing required field 'goal'
      2. Task 'write_report': references unknown agent 'writer' (not defined in agents/roles)

    Additionally, there are 1 warning(s):
      1. Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.
    ```

    Exit code: `1`
  </Step>

  <Step title="CI usage — strict mode + JSON output">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate agents.yaml --strict --json
    ```

    Output:

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "file": "agents.yaml",
      "valid": false,
      "errors": [
        "Agent 'researcher': missing required field 'goal'"
      ],
      "warnings": [
        "Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored."
      ],
      "strict_mode": true
    }
    ```

    With `--strict`, warnings are also treated as errors, so exit code is `1` even when only warnings are present.
  </Step>

  <Step title="Emit machine-readable schema">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate schema --agents > agents.schema.json
    # or
    praisonai validate schema -o agents.schema.json
    ```

    Point your editor's YAML language server at the file for autocomplete and inline validation — see [Editor Support](/docs/features/editor-support).
  </Step>
</Steps>

***

## Subcommands

| Command                                | Purpose                                                                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `praisonai validate <file>`            | Validate a single YAML file                                                                                                                  |
| `praisonai validate check [directory]` | Validate every YAML file in a directory                                                                                                      |
| `praisonai validate schema`            | Print the YAML config schema (fields, types, required markers), or emit the machine-readable JSON Schema with `--agents` / `--output` / `-o` |

***

## Flags

### `praisonai validate <file>`

| Flag                | Type   | Default | Description                                 |
| ------------------- | ------ | ------- | ------------------------------------------- |
| `file` (positional) | `str`  | —       | Path to YAML config to validate             |
| `--strict`          | `bool` | `False` | Treat warnings as errors                    |
| `--quiet` / `-q`    | `bool` | `False` | Only show errors, suppress success messages |
| `--json`            | `bool` | `False` | Emit results as JSON (for CI)               |

### `praisonai validate check [directory]`

| Flag                     | Type   | Default    | Description                                                      |
| ------------------------ | ------ | ---------- | ---------------------------------------------------------------- |
| `directory` (positional) | `str`  | `"."`      | Directory to search for YAML files                               |
| `--pattern` / `-p`       | `str`  | `"*.yaml"` | Glob pattern (also auto-includes `*.yml` when using the default) |
| `--strict`               | `bool` | `False`    | Treat warnings as errors                                         |
| `--stop-on-error`        | `bool` | `False`    | Stop on the first invalid file                                   |

### `praisonai validate schema`

With no flags, prints all main config sections with field names, types, and required markers. Two flags emit the machine-readable JSON Schema instead:

| Flag              | Type   | Default | Description                                                                                                                      |
| ----------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `--agents`        | `bool` | `False` | Emit the machine-readable JSON Schema for `agents.yaml` (derived from `YAMLConfig`) instead of the human-readable summary        |
| `--output` / `-o` | `str`  | `None`  | Write the JSON Schema to a file instead of stdout (implies `--agents`; prints `✓ Wrote agents JSON Schema to <path>` on success) |

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai validate schema --agents               # print JSON Schema to stdout
praisonai validate schema -o agents.schema.json  # write JSON Schema to a file
```

Point your editor's YAML language server at that schema for autocomplete and inline validation — see [Editor Autocomplete](/docs/features/editor-autocomplete).

***

## What Gets Validated

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Validation Pipeline"
        A["📋 agents.yaml"] --> B["1️⃣ Schema Check"]
        B --> C["2️⃣ Cross-Reference Check"]
        C --> D["3️⃣ Tool Check"]
        D --> E["4️⃣ Unknown Fields"]
    end

    B --> B1["Required fields present?\nTypes correct?\nEnum values valid?"]
    C --> C1["task.agent → exists in roles?\nworkflow step agent → exists?\nhandoff.to → exists?"]
    D --> D1["Unknown name → error\nKnown optional / TOOL_MAPPINGS → warning"]
    E --> E1["Unknown keys → warning\n(not error)"]

    classDef file fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef check fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef detail fill:#6366F1,stroke:#7C90A0,color:#fff

    class A file
    class B,C,D,E check
    class B1,C1,D1,E1 detail
```

### 1. Schema Validation

Enforces the Pydantic schema. Every agent must have **`role`**, **`goal`**, and **`backstory`** — these are required. Every task must have **`description`** and **`agent`** (matching `^[a-zA-Z0-9_-]+$`).

When `process: workflow`, the config must also include `steps` or `workflow`.

### 2. Cross-Reference Validation

* Every `tasks[i].agent` must name an agent defined under `roles` / `agents`
* Workflow step `agent` fields are validated recursively (through nested `steps` and `routes`)
* Every `handoff.to` target must resolve to a known role

### 3. Tool Validation

Tool names are resolved through `ToolResolver.resolve(name)`:

* **Unknown tool** → **error**: *"Unknown tool 'X'. Ensure it's properly installed or defined in your configuration."* — the name doesn't exist in the local `tools.py`, the wrapper registry, [`TOOL_MAPPINGS`](/docs/features/tool-discovery-order), `praisonai-tools`, or any registered plugin.
* **Known optional tool** → **warning**: *"Tool 'X' requires additional dependencies. Install with: pip install 'praisonai\[tools]' …"* — the name is recognised (either in the hardcoded optional-tool list or in [`TOOL_MAPPINGS`](/docs/features/tool-discovery-order)), but the optional dependency isn't installed.

Recognised optional-tool families include database (`PostgreSQLTool`, `MongoDBTool`, `RedisTool`, `ElasticsearchTool`, …), messaging (`SlackTool`, `DiscordTool`, `TelegramTool`, `EmailTool`, `TwitterTool`, `LinkedInTool`, `GitHubTool`), cloud (`AWSTool`, `AzureTool`, `GCPTool`, `S3Tool`), AI/ML (`HuggingFaceTool`, `OpenAITool`, `AnthropicTool`), data (`PandasTool`, `NumpyTool`, `ScipyTool`), and browser/infra (`BrowserTool`, `SeleniumTool`, `PlaywrightTool`, `KubernetesTool`, `DockerTool`, `TerraformTool`). Any built-in tool declared in [`TOOL_MAPPINGS`](/docs/features/tool-discovery-order) (e.g. `duckduckgo`, `wiki_search`, `execute_code`, `crawl4ai`) is also treated as a known tool — missing deps yield a warning, not an error.

<Note>
  **Behaviour change (PraisonAI [#4331](https://github.com/MervinPraison/PraisonAI/pull/4331))**: earlier releases silently downgraded every tool check to a generic *"Could not validate tool 'X'"* warning because of an internal `AttributeError`. If your CI didn't previously fail on misspelled or missing tool names, upgrading to a release that includes #4331 will start flagging them as errors — this is the intended behaviour and the docs above.
</Note>

### 4. Unknown Fields

Top-level unknown keys and unknown agent/role fields produce **warnings**, not errors:

*"Unknown agent field 'X'. This field will be ignored."*

<Note>
  Unknown-field warnings are non-blocking — your workflow still runs. Only errors (missing required fields, bad cross-references, unknown tools) cause a hard failure.
</Note>

***

## Output Formats

<Tabs>
  <Tab title="Plain (Rich)">
    Default output uses Rich formatting for easy reading in the terminal:

    ```
    ✅ agents.yaml is valid
      Warnings:
        • Unknown agent field 'stream' in agent 'writer'. This field will be ignored.
    ```

    ```
    ❌ agents.yaml is invalid

    Configuration validation failed with 2 error(s):
      1. Agent 'researcher': missing required field 'goal'
      2. Task 'write_report': references unknown agent 'writer' (not defined in agents/roles)

    Additionally, there are 1 warning(s):
      1. Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored.
    ```
  </Tab>

  <Tab title="Quiet (-q)">
    Only errors are printed; success messages and warnings are suppressed:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate agents.yaml -q
    ```

    Produces no output when valid. On error, only the error block is shown.
  </Tab>

  <Tab title="JSON (--json)">
    Structured output for CI pipelines:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai validate agents.yaml --json
    ```

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "file": "agents.yaml",
      "valid": true,
      "errors": [],
      "warnings": [],
      "strict_mode": false
    }
    ```

    When invalid:

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "file": "agents.yaml",
      "valid": false,
      "errors": [
        "Agent 'researcher': missing required field 'goal'"
      ],
      "warnings": [
        "Unknown agent field 'instrutions' in agent 'researcher'. This field will be ignored."
      ],
      "strict_mode": false
    }
    ```
  </Tab>

  <Tab title="Directory Scan">
    `praisonai validate check` renders a Rich table:

    ```
    ┌──────────────────┬─────────┬────────┬──────────┐
    │ File             │ Status  │ Errors │ Warnings │
    ├──────────────────┼─────────┼────────┼──────────┤
    │ agents.yaml      │ ✅ PASS │ 0      │ 1        │
    │ workflow.yaml    │ ❌ FAIL │ 2      │ 0        │
    └──────────────────┴─────────┴────────┴──────────┘

    Summary: 1/2 files valid
    ```
  </Tab>
</Tabs>

***

## CI Integration

Add validation to your GitHub Actions workflow to block merges on broken configs:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
name: Validate PraisonAI Config
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install PraisonAI
        run: pip install praisonai

      - name: Validate all YAML configs
        run: praisonai validate check . --strict --json
```

Exit code `1` on any validation failure causes the step to fail.

***

## Strict Mode

Strict mode promotes warnings to errors — useful in CI to keep configs clean.

Enable per-command:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai validate agents.yaml --strict
praisonai validate check . --strict
```

Enable globally via environment variable:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_VALIDATE_STRICT=true
praisonai validate agents.yaml
```

With `PRAISONAI_VALIDATE_STRICT=true`, **all** validation runs (including the automatic pre-run check in `agents_generator.py`) use strict mode.

### Runtime YAML normalisation (`_normalize_yaml_config`)

Even without running `praisonai validate` explicitly, every `praisonai start agents.yaml` normalises the YAML — and now catches three silent bugs that used to cause agents to disappear.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Load[📄 YAML load] --> Check{Duplicate name<br/>or unknown ref?}
    Check -->|no| Ok[✅ Normalise]
    Check -->|yes| Strict{PRAISONAI_VALIDATE_STRICT?}
    Strict -->|true| Raise[❌ raise ValueError]
    Strict -->|false| Warn[⚠️ Warn + preserve<br/>with __dup_i suffix]
    Warn --> Ok

    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef bad fill:#8B0000,stroke:#7C90A0,color:#fff

    class Load start
    class Check,Strict decision
    class Ok,Warn ok
    class Raise bad
```

Three rules run during normalisation, all gated by `PRAISONAI_VALIDATE_STRICT`:

| Situation                                        | Non-strict (default)                                                                                                                             | Strict (`PRAISONAI_VALIDATE_STRICT=true`) |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| Two agents (or roles) with the same `name`       | `WARNING: Duplicate agent name(s) in YAML: ['researcher']`; both preserved as `researcher` and `researcher__dup_1`                               | `raise ValueError` — run aborts           |
| A `task.agent` referencing an undefined agent    | `WARNING: Task 'x' references unknown agent 'y'; skipping.`; task is dropped                                                                     | `raise ValueError` — run aborts           |
| Two tasks with the same `name` on the same agent | `WARNING: Duplicate task name 'x' for agent 'y' in YAML — kept both by suffixing keys; rename to silence.`; both preserved as `x` and `x__dup_i` | `raise ValueError` — run aborts           |

Toggle strict mode to abort instead of warn:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_VALIDATE_STRICT=true
praisonai start agents.yaml
```

The `__dup_i` suffix marks a preserved duplicate. Given a list-form config with two `researcher` agents:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  - name: researcher
    role: Research Analyst
    goal: Research topics
    backstory: Expert researcher.
  - name: researcher
    role: Second Researcher
    goal: Research topics
    backstory: Another researcher.
```

Non-strict output keeps both agents so nothing silently vanishes:

```
WARNING: Duplicate agent name(s) in YAML: ['researcher'] — kept both by suffixing keys; rename to silence.
```

The second agent is stored under `researcher__dup_1`. If you see `researcher__dup_1` in traces or logs, it means a duplicate `name` was collapsed — rename one entry to silence the warning.

***

## Exit Codes

| Code | Meaning                                              |
| ---- | ---------------------------------------------------- |
| `0`  | File is valid (or all files in directory are valid)  |
| `1`  | One or more errors found, or the file does not exist |

***

## Backward-Compatible Aliases

The validator automatically normalises these field aliases — you can use either form:

| Alias     | Canonical    |
| --------- | ------------ |
| `agents:` | `roles:`     |
| `topic:`  | `input:`     |
| `stream:` | `streaming:` |

***

## Fail-Fast Runtime Validation

When you run `praisonai start agents.yaml`, validation now runs automatically **before** execution. If any errors are found, the run aborts with an aggregated `ValueError`:

```
Configuration validation failed with 2 error(s):
  1. Agent 'researcher': missing required field 'goal'
  2. Task 'write_report': references unknown agent 'writer'

Additionally, there are 1 warning(s):
  1. Unknown agent field 'instrutions'. This field will be ignored.
```

This replaces the old behaviour where invalid configs emitted non-blocking warnings and continued running.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Run validate before every commit">
    Add `praisonai validate agents.yaml` to your pre-commit checks or CI pipeline to catch errors early.
  </Accordion>

  <Accordion title="Use --json in automated pipelines">
    JSON output is easy to parse in scripts or CI steps that need to inspect specific error messages programmatically.
  </Accordion>

  <Accordion title="Set PRAISONAI_VALIDATE_STRICT=true in production">
    Strict mode treats warnings as errors, preventing unknown or misspelled fields from silently being ignored in production environments.
  </Accordion>

  <Accordion title="Use validate schema to discover required fields">
    Run `praisonai validate schema` to see all fields, their types, and which are required — before writing a new config from scratch.
  </Accordion>

  <Accordion title="Wire your editor to the schema for autocomplete">
    Emit the JSON Schema with `praisonai validate schema --agents` (or pin it with `-o agents.schema.json`) and point your editor's YAML language server at it for autocomplete and inline validation. See [Editor Autocomplete](/docs/features/editor-autocomplete).
  </Accordion>

  <Accordion title="Re-validate configs after upgrading past PR #4331">
    Releases that include [PR #4331](https://github.com/MervinPraison/PraisonAI/pull/4331) start flagging tool typos and missing tools as errors that older releases silently allowed. Run `praisonai validate check . --strict` on your existing configs before your next deploy to surface anything the earlier code let through.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="YAML Configuration Reference" icon="book" href="/docs/features/yaml-configuration-reference">
    Complete field reference for agents.yaml and workflow\.yaml
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/docs/features/cli">
    All available CLI commands
  </Card>

  <Card title="Doctor" icon="stethoscope" href="/docs/cli/doctor">
    Diagnose environment and dependency issues
  </Card>

  <Card title="Workflow CLI" icon="diagram-project" href="/docs/cli/workflow">
    Run and manage YAML workflows from the terminal
  </Card>

  <Card title="Editor Autocomplete" icon="code" href="/docs/features/editor-autocomplete">
    Wire agents.yaml to your editor for autocomplete and inline validation
  </Card>
</CardGroup>