{"record":{"id":"f86608a7fb00816c","repo":"crewAIInc/crewAI","slug":"tool-crewai-definition-must-be-relative-to-the-p","errorCode":null,"errorMessage":"[tool.crewai] definition must be relative to the project root; got {definition!r}.","messagePattern":"\\[tool\\.crewai\\] definition must be relative to the project root; got (.+?)\\.","errorType":"exception","errorClass":"ProjectDefinitionError","httpStatus":null,"severity":"error","filePath":"lib/crewai-core/src/crewai_core/project.py","lineNumber":111,"sourceCode":"        )\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\n    try:\n        resolved_candidate = candidate.resolve(strict=False)\n    except OSError as exc:\n        raise ProjectDefinitionError(\n            f\"Invalid [tool.crewai] definition path {definition!r}: {exc}\"\n        ) from exc","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-core/src/crewai_core/project.py#L93-L129","documentation":"Raised when the [tool.crewai] definition is an absolute path (checked both as a POSIX path and as a Windows path via PureWindowsPath, so 'C:\\\\crew\\\\main.py' is caught on Linux too). Absolute paths would let a project point at files outside its root, so the resolver only accepts root-relative values. Thrown as ProjectDefinitionError from resolve_project_definition_path.","triggerScenarios":"definition = \"/home/user/crew/main.py\" or definition = \"C:\\\\Users\\\\me\\\\crew\\\\main.py\" in [tool.crewai], then calling resolve_project_definition_path with the project root; any leading-slash or drive-letter string triggers it.","commonSituations":"Migrating a crew whose layout used absolute paths, Windows users pasting Explorer paths into pyproject.toml, or CI configs that inject absolute paths via environment variables.","solutions":["Rewrite the definition as a path relative to the project root (drop the leading slash or drive prefix).","Verify you are editing the pyproject.toml that sits at the root you pass as project_root; relative paths are resolved against that root.","For CI, compute the relative portion of the path before writing it into the TOML file."],"exampleFix":"# before\n[tool.crewai]\ndefinition = \"/opt/crews/sales/main.py\"\n\n# after\n[tool.crewai]\ndefinition = \"src/sales/main.py\"","handlingStrategy":"validation","validationCode":"from pathlib import Path, PureWindowsPath\n\ndef is_relative_definition(definition: str) -> bool:\n    return not Path(definition).is_absolute() and not PureWindowsPath(definition).is_absolute()","typeGuard":null,"tryCatchPattern":"except ProjectDefinitionError as e:\n    # message contains 'must be relative to the project root'\n    raise ConfigError(str(e)) from e","preventionTips":["Store definitions as repo-relative paths in templates so absolute paths never enter the TOML.","CI check: reject [tool.crewai].definition values starting with '/', a drive letter, or '~'."],"tags":["configuration","pyproject-toml","path-validation","cross-platform"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}