crewAIInc/crewAI · error · SystemExit

Invalid --definition path: {definition} ({exc})

Error message

Invalid --definition path: {definition} ({exc})

What it means

OSError raised while probing the --definition path (the exists()/is_file() calls are wrapped in try/except OSError). This means the filesystem itself errored — not that the file is missing or is a directory (those have dedicated messages). Typical causes include permission-denied on a parent directory, stale NFS handles, or path resolution failures. Message includes the original OSError text; exits 1.

Source

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

        )
        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:
    """Return the configured declarative flow source for flow projects."""
    root = project_root or Path.cwd()
    if pyproject_data is None and not (root / "pyproject.toml").is_file():

View on GitHub (pinned to 754d7323be)

Solutions

1. Read the parenthesized OSError — 'Permission denied' means fixing perms (`chmod`/`chown` or run as the right user); 'Not a directory' means a path component is a file.
2. Test manually: `ls -la <path>` and `realpath <path>` to surface the same OS error.
3. Remove/fix broken symlinks or mount points in the path.
4. Move/copy the definition to a readable location and pass that path.

Example fix

# before
$ crewai flow run --definition /root/flows/flow.yaml  # running as non-root
# Invalid --definition path: /root/flows/flow.yaml ([Errno 13] Permission denied)

# after
$ sudo cp /root/flows/flow.yaml ./flow.yaml && crewai flow run --definition ./flow.yaml

import os
from pathlib import Path

path = Path(definition_arg).expanduser()
try:
    if not path.exists():
        raise SystemExit(f"path not accessible: {path}")
except OSError as exc:
    raise SystemExit(f"filesystem error probing {path}: {exc}")

try:
    ok = Path(definition).expanduser().is_file()
except OSError as exc:
    # permission / stale-mount issues: report the OS error verbatim
    raise SystemExit(f"cannot probe {definition}: {exc}") from exc

When it happens

Trigger: definition_path.exists() raising PermissionError (EACCES) on an unreadable parent dir; OSError (ENOTDIR / ELOOP / ESTALE) when the path mixes a file where a directory component is expected, symlink loops, or NFS disconnects; ~ expansion landing on an unavailable mount.

Common situations: Hardened CI containers running as non-root reading paths under /root; broken symlinks in the path; network filesystems dropping out; Docker volume mount permission mismatches.

Related errors

• Invalid --definition path: {definition} is not a file.
• Invalid --definition path: {definition} does not exist.
• An error occurred while plotting the flow: {e}
• An unexpected error occurred: {e}
• An error occurred while running the declarative flow: {exc}

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