crewAIInc/crewAI · error · SystemExit

Unable to read --definition path {definition_path}: {exc}

Error message

Unable to read --definition path {definition_path}: {exc}

What it means

Flow.from_declaration(path=definition_path) raised one of OSError, UnicodeError, ValueError, or ValidationError. The file exists and is readable, but loading it as a declaration failed: unreadable bytes (UnicodeDecodeError is a UnicodeError), I/O failure mid-read, or the parsed content is not a valid declarative flow definition (ValueError/ValidationError from schema validation). Exits 1 with the cause chained.

Source

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

                    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():
        return None

    try:
        return configured_project_definition(
            "flow",
            pyproject_data=pyproject_data,
            project_root=root,
        )
    except ProjectDefinitionError as exc:

View on GitHub (pinned to 754d7323be)

Solutions

1. Read the message — ValidationError text names the exact field and problem; fix the definition accordingly.
2. Validate the file parses: `python -c "import yaml,sys; yaml.safe_load(open('flow.yaml'))"` (or json.load for JSON).
3. Re-save the file as UTF-8 if the error mentions encoding/decoding.
4. Diff against a known-working definition from the docs for the installed crewai version; schema keys change between versions.

Example fix

# before
# flow.yaml missing required 'steps'
$ crewai flow run --definition flow.yaml
# Unable to read --definition path flow.yaml: Field required [type=missing, ...]

# after
# flow.yaml
name: my_flow
steps:
  - id: research
    method: research_task
$ crewai flow run --definition flow.yaml

from pathlib import Path
import yaml  # or json, matching your definition format

raw = Path("flow.yaml").read_text(encoding="utf-8")  # raises UnicodeDecodeError early
declaration = yaml.safe_load(raw)  # raises on malformed YAML
assert isinstance(declaration, dict), "definition must be a mapping at top level"

def looks_like_flow_declaration(data: object) -> bool:
    """Cheap structural check before handing the file to Flow.from_declaration."""
    return isinstance(data, dict) and "steps" in data

from pydantic import ValidationError

try:
    flow = Flow.from_declaration(path=path)
except ValidationError as exc:
    # schema errors: print loc+msg per error and fix the definition
    for e in exc.errors():
        print("definition error:", e["loc"], e["msg"])
    raise SystemExit(1) from exc
except (OSError, UnicodeError, ValueError) as exc:
    raise SystemExit(f"unreadable definition: {exc}") from exc

When it happens

Trigger: A YAML/JSON definition with schema violations — missing required keys (e.g. no steps), wrong value types, unknown structure — surfaced as ValidationError; a file saved in a non-UTF-8 encoding producing UnicodeDecodeError; truncated writes producing YAML parse errors (typically ValueError subclasses).

Common situations: Hand-editing flow definitions and breaking indentation; generators/templates emitting partial YAML; files edited on Windows saved as UTF-16; version drift between the definition schema the user copied from docs and the installed crewai version.

Related errors

• Missing required input '{name}'{suffix}
• An error occurred while running the declarative flow: {exc}
• Invalid input '{location}': {error.get('msg')}
• An error occurred while plotting the declarative flow: {exc}
• Invalid --definition path: {definition} is not a file.

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