{"record":{"id":"7683211e00cf7eee","repo":"crewAIInc/crewAI","slug":"invalid-definition-path-definition-exc","errorCode":null,"errorMessage":"Invalid --definition path: {definition} ({exc})","messagePattern":"Invalid --definition path: (.+?) \\((.+?)\\)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/run_declarative_flow.py","lineNumber":437,"sourceCode":"        )\n        raise SystemExit(1) from exc\n\n    definition_path = Path(definition).expanduser()\n    try:\n        if not definition_path.is_file():\n            if definition_path.exists():\n                click.echo(\n                    f\"Invalid --definition path: {definition} is not a file.\",\n                    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():","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L419-L455","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Test manually: `ls -la <path>` and `realpath <path>` to surface the same OS error.","Remove/fix broken symlinks or mount points in the path.","Move/copy the definition to a readable location and pass that path."],"exampleFix":"# before\n$ crewai flow run --definition /root/flows/flow.yaml  # running as non-root\n# Invalid --definition path: /root/flows/flow.yaml ([Errno 13] Permission denied)\n\n# after\n$ sudo cp /root/flows/flow.yaml ./flow.yaml && crewai flow run --definition ./flow.yaml","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\npath = Path(definition_arg).expanduser()\ntry:\n    if not path.exists():\n        raise SystemExit(f\"path not accessible: {path}\")\nexcept OSError as exc:\n    raise SystemExit(f\"filesystem error probing {path}: {exc}\")","typeGuard":null,"tryCatchPattern":"try:\n    ok = Path(definition).expanduser().is_file()\nexcept OSError as exc:\n    # permission / stale-mount issues: report the OS error verbatim\n    raise SystemExit(f\"cannot probe {definition}: {exc}\") from exc","preventionTips":["Verify read permission on every directory component: `namei -l <path>` shows where access stops.","Avoid symlink chains in project paths; prefer real directories.","In containers, ensure the run user owns or can read the mounted definition path."],"tags":["path","permissions","os-error","flow","cli"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}