{"record":{"id":"499534b6e3548547","repo":"crewAIInc/crewAI","slug":"invalid-definition-path-definition-is-not-a-f","errorCode":null,"errorMessage":"Invalid --definition path: {definition} is not a file.","messagePattern":"Invalid --definition path: (.+?) is not a file\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/run_declarative_flow.py","lineNumber":430,"sourceCode":"    \"\"\"Load a declarative Flow instance from a definition path.\"\"\"\n    try:\n        from crewai.flow.flow import Flow\n    except ImportError as exc:\n        click.echo(\n            \"Running declarative flows requires the full crewai package.\",\n            err=True,\n        )\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","sourceCodeStart":412,"sourceCodeEnd":448,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L412-L448","documentation":"Path validation in load_declarative_flow(): definition_path.exists() is True but definition_path.is_file() is False — the --definition argument resolves to a directory (or other non-file filesystem entry). The CLI prints the message to stderr and exits 1 before any parsing is attempted.","triggerScenarios":"Passing a directory to --definition, e.g. `crewai flow run --definition ./flows` when the file is `./flows/flow.yaml`; shell tab-completion stopping at the directory; passing `.` intending 'current project'.","commonSituations":"Projects that keep multiple definitions in a folder and users passing the folder; copied commands from docs that use a placeholder directory path.","solutions":["Point --definition at the actual definition file (YAML/JSON) inside the directory.","Use tab-completion to the file, or ls the directory to find the right filename.","If the definition path is configured in pyproject.toml, correct it there too."],"exampleFix":"# before\n$ crewai flow run --definition ./flows\n# Invalid --definition path: ./flows is not a file.\n\n# after\n$ crewai flow run --definition ./flows/flow.yaml","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef assert_definition_file(p: str) -> Path:\n    path = Path(p).expanduser()\n    if not path.is_file():\n        raise SystemExit(f\"--definition must be a file, got: {p}\")\n    return path","typeGuard":"from pathlib import Path\n\ndef is_definition_file(p: str | Path) -> bool:\n    \"\"\"True when p resolves to an existing regular file.\"\"\"\n    path = Path(p).expanduser()\n    return path.is_file()","tryCatchPattern":null,"preventionTips":["Complete paths to the file, not the folder, when scripting (tab-complete to the end).","Store the definition filename in one config var and derive all commands from it.","In docs/runbooks, show full file paths like `flows/flow.yaml`, never bare directories."],"tags":["validation","path","flow","user-input","cli"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}