crewAIInc/crewAI · error · SystemExit

Invalid --definition path: {definition} does not exist.

Error message

Invalid --definition path: {definition} does not exist.

What it means

Path validation in load_declarative_flow(): definition_path.is_file() is False and definition_path.exists() is also False — the --definition argument points at a path that does not exist on disk. Expansion with expanduser() happens first, so '~/...' paths are honored. The CLI prints the message to stderr and exits 1.

Source

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

        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


def configured_project_declarative_flow(
    pyproject_data: dict[str, Any] | None = None,
    project_root: Path | None = None,
) -> Path | None:

View on GitHub (pinned to 754d7323be)

Solutions

1. Check the file exists: `ls -la <path>` from the same directory you run the command in.
2. Use an absolute path or correct relative path (relative to the current working directory, not the project root).
3. If the file is gitignored/missing in CI, commit it or generate it in the pipeline.
4. Update the definition path in pyproject.toml if it is configured there.

Example fix

# before
$ crewai flow run --definition flows/flow.yml   # actual name: flow.yaml
# Invalid --definition path: flows/flow.yml does not exist.

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

from pathlib import Path

path = Path(definition_arg).expanduser().resolve()
if not path.exists():
    raise SystemExit(f"definition file not found: {path}")

from pathlib import Path

def definition_exists(p: str | Path) -> bool:
    return Path(p).expanduser().resolve().exists()

When it happens

Trigger: Typo in the path; running the command from a different working directory so a relative path doesn't resolve; the definition file not yet created; a deleted/moved file; a configured pyproject path that no longer exists.

Common situations: Running `crewai flow ...` from a subdirectory instead of the project root; CI checkout missing the definition file because it's gitignored; renamed files.

Related errors

• Invalid --definition path: {definition} is not a file.
• Invalid --definition path: {definition} ({exc})
• Invalid JSON payload provided as argument
• project_name is required to update a ZIP deployment
• project_name is required to create a deployment payload

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