{"record":{"id":"8da357d3eecd2dbc","repo":"crewAIInc/crewAI","slug":"unable-to-read-definition-path-definition-path","errorCode":null,"errorMessage":"Unable to read --definition path {definition_path}: {exc}","messagePattern":"Unable to read --definition path (.+?): (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/run_declarative_flow.py","lineNumber":446,"sourceCode":"                    err=True,\n                )\n                raise SystemExit(1)\n            click.echo(\n                f\"Invalid --definition path: {definition} does not exist.\", err=True\n            )\n            raise SystemExit(1)\n    except OSError as exc:\n        click.echo(f\"Invalid --definition path: {definition} ({exc})\", err=True)\n        raise SystemExit(1) from exc\n\n    try:\n        return Flow.from_declaration(path=definition_path)\n    except (OSError, UnicodeError, ValueError, ValidationError) as exc:\n        click.echo(\n            f\"Unable to read --definition path {definition_path}: {exc}\",\n            err=True,\n        )\n        raise SystemExit(1) from exc\n\n\ndef configured_project_declarative_flow(\n    pyproject_data: dict[str, Any] | None = None,\n    project_root: Path | None = None,\n) -> Path | None:\n    \"\"\"Return the configured declarative flow source for flow projects.\"\"\"\n    root = project_root or Path.cwd()\n    if pyproject_data is None and not (root / \"pyproject.toml\").is_file():\n        return None\n\n    try:\n        return configured_project_definition(\n            \"flow\",\n            pyproject_data=pyproject_data,\n            project_root=root,\n        )\n    except ProjectDefinitionError as exc:","sourceCodeStart":428,"sourceCodeEnd":464,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L428-L464","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the message — ValidationError text names the exact field and problem; fix the definition accordingly.","Validate the file parses: `python -c \"import yaml,sys; yaml.safe_load(open('flow.yaml'))\"` (or json.load for JSON).","Re-save the file as UTF-8 if the error mentions encoding/decoding.","Diff against a known-working definition from the docs for the installed crewai version; schema keys change between versions."],"exampleFix":"# before\n# flow.yaml missing required 'steps'\n$ crewai flow run --definition flow.yaml\n# Unable to read --definition path flow.yaml: Field required [type=missing, ...]\n\n# after\n# flow.yaml\nname: my_flow\nsteps:\n  - id: research\n    method: research_task\n$ crewai flow run --definition flow.yaml","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport yaml  # or json, matching your definition format\n\nraw = Path(\"flow.yaml\").read_text(encoding=\"utf-8\")  # raises UnicodeDecodeError early\ndeclaration = yaml.safe_load(raw)  # raises on malformed YAML\nassert isinstance(declaration, dict), \"definition must be a mapping at top level\"","typeGuard":"def looks_like_flow_declaration(data: object) -> bool:\n    \"\"\"Cheap structural check before handing the file to Flow.from_declaration.\"\"\"\n    return isinstance(data, dict) and \"steps\" in data","tryCatchPattern":"from pydantic import ValidationError\n\ntry:\n    flow = Flow.from_declaration(path=path)\nexcept ValidationError as exc:\n    # schema errors: print loc+msg per error and fix the definition\n    for e in exc.errors():\n        print(\"definition error:\", e[\"loc\"], e[\"msg\"])\n    raise SystemExit(1) from exc\nexcept (OSError, UnicodeError, ValueError) as exc:\n    raise SystemExit(f\"unreadable definition: {exc}\") from exc","preventionTips":["Lint definitions in CI: parse the YAML/JSON and run Flow.from_declaration as a check step before deploy.","Save definition files as UTF-8 without BOM; avoid Windows editors defaulting to UTF-16.","Track schema changes across crewai versions — re-validate definitions after upgrades."],"tags":["validation","yaml","flow","declarative","schema","encoding"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}