crewAIInc/crewAI · error · SystemExit

Invalid --definition path: {definition} is not a file.

Error message

Invalid --definition path: {definition} is not a file.

What it means

Path validation in load_declarative_flow(): definition_path.exists() is True but definition_path.is_file() is False — the --definition argument resolves to a directory (or other non-file filesystem entry). The CLI prints the message to stderr and exits 1 before any parsing is attempted.

Source

Thrown at lib/cli/src/crewai_cli/run_declarative_flow.py:430

    """Load a declarative Flow instance from a definition path."""
    try:
        from crewai.flow.flow import Flow
    except ImportError as exc:
        click.echo(
            "Running declarative flows requires the full crewai package.",
            err=True,
        )
        raise SystemExit(1) from exc

    definition_path = Path(definition).expanduser()
    try:
        if not definition_path.is_file():
            if definition_path.exists():
                click.echo(
                    f"Invalid --definition path: {definition} is not a file.",
                    err=True,
                )
                raise SystemExit(1)
            click.echo(
                f"Invalid --definition path: {definition} does not exist.", err=True
            )
            raise SystemExit(1)
    except OSError as exc:
        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
        raise SystemExit(1) from exc

    try:
        return Flow.from_declaration(path=definition_path)
    except (OSError, UnicodeError, ValueError, ValidationError) as exc:
        click.echo(
            f"Unable to read --definition path {definition_path}: {exc}",
            err=True,
        )
        raise SystemExit(1) from exc

View on GitHub (pinned to 754d7323be)

Solutions

1. Point --definition at the actual definition file (YAML/JSON) inside the directory.
2. Use tab-completion to the file, or ls the directory to find the right filename.
3. If the definition path is configured in pyproject.toml, correct it there too.

Example fix

# before
$ crewai flow run --definition ./flows
# Invalid --definition path: ./flows is not a file.

# after
$ crewai flow run --definition ./flows/flow.yaml

from pathlib import Path

def assert_definition_file(p: str) -> Path:
    path = Path(p).expanduser()
    if not path.is_file():
        raise SystemExit(f"--definition must be a file, got: {p}")
    return path

from pathlib import Path

def is_definition_file(p: str | Path) -> bool:
    """True when p resolves to an existing regular file."""
    path = Path(p).expanduser()
    return path.is_file()

When it happens

Trigger: Passing a directory to --definition, e.g. `crewai flow run --definition ./flows` when the file is `./flows/flow.yaml`; shell tab-completion stopping at the directory; passing `.` intending 'current project'.

Common situations: Projects that keep multiple definitions in a folder and users passing the folder; copied commands from docs that use a placeholder directory path.

Related errors

• Invalid --definition path: {definition} does not exist.
• Template '{name}' not found.
• Missing required input '{name}'
• Invalid --definition path: {definition} ({exc})
• Error: Unknown or readonly configuration key '{key}'

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/499534b6e3548547. Report an issue: GitHub.