{"record":{"id":"1b6b82297893f6ce","repo":"crewAIInc/crewAI","slug":"tool-crewai-definition-must-be-a-project-local-p","errorCode":null,"errorMessage":"[tool.crewai] definition must be a project-local path; got {definition!r}.","messagePattern":"\\[tool\\.crewai\\] definition must be a project-local path; got (.+?)\\.","errorType":"exception","errorClass":"ProjectDefinitionError","httpStatus":null,"severity":"error","filePath":"lib/crewai-core/src/crewai_core/project.py","lineNumber":105,"sourceCode":"        )\n\n    definition = raw_definition.strip()\n    if not definition:\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must be a non-empty project-local path.\"\n        )\n\n    return resolve_project_definition_path(definition=definition, project_root=root)\n\n\ndef resolve_project_definition_path(definition: str, project_root: Path | str) -> Path:\n    \"\"\"Resolve a ``[tool.crewai].definition`` path inside ``project_root``.\"\"\"\n    root_path = Path(project_root)\n    definition_path = Path(definition)\n    windows_definition_path = PureWindowsPath(definition)\n\n    if definition.startswith(\"~\"):\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must be a project-local path; \"\n            f\"got {definition!r}.\"\n        )\n\n    if definition_path.is_absolute() or windows_definition_path.is_absolute():\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must be relative to the project root; \"\n            f\"got {definition!r}.\"\n        )\n\n    try:\n        root = root_path.resolve(strict=True)\n    except OSError as exc:\n        raise ProjectDefinitionError(\n            f\"Invalid project root for [tool.crewai] definition: {exc}\"\n        ) from exc\n\n    candidate = root / definition_path","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-core/src/crewai_core/project.py#L87-L123","documentation":"Raised by resolve_project_definition_path when the [tool.crewai] definition value in pyproject.toml starts with '~'. The library requires the definition path to be project-local so it can be resolved against the project root; home-directory shortcuts are rejected explicitly before other checks. It surfaces as a ProjectDefinitionError so tooling can present a clear config message.","triggerScenarios":"Setting [tool.crewai] definition = \"~/projects/my-crew/main.py\" (or any '~'-prefixed string) in pyproject.toml, then calling any API that resolves the project definition path, e.g. resolve_project_definition_path(definition=\"~/x.py\", project_root=...).","commonSituations":"Users copy a template pyproject.toml from a machine where the crew lived in the home directory, or convert an absolute home path into '~' shorthand expecting expansion. Also appears when a YAML/TOML variable is interpolated with $HOME.","solutions":["Change definition in pyproject.toml to a path relative to the project root, e.g. definition = \"src/my_crew/main.py\".","If the file really lives outside the project, copy it into the project directory first, then reference the copy relatively.","Never rely on shell expansion: TOML strings are not expanded, so '~' or '$HOME' will never resolve."],"exampleFix":"# before\n[tool.crewai]\ndefinition = \"~/crews/my_crew/main.py\"\n\n# after\n[tool.crewai]\ndefinition = \"src/my_crew/main.py\"","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef definition_ok(definition: str) -> bool:\n    return not definition.startswith(\"~\")","typeGuard":null,"tryCatchPattern":"from crewai_core.project import ProjectDefinitionError\ntry:\n    path = resolve_project_definition_path(definition, root)\nexcept ProjectDefinitionError as e:\n    print(f\"Bad [tool.crewai] definition config: {e}\")","preventionTips":["Lint pyproject.toml in CI: assert the [tool.crewai].definition value is relative and contains no '~'.","Treat TOML strings as literal — never expect shell expansion."],"tags":["configuration","pyproject-toml","path-validation"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}