{"record":{"id":"b8372a18201227bc","repo":"crewAIInc/crewAI","slug":"invalid-tool-crewai-definition-path-definition","errorCode":null,"errorMessage":"Invalid [tool.crewai] definition path {definition!r}: {exc}","messagePattern":"Invalid \\[tool\\.crewai\\] definition path (.+?): (.+?)","errorType":"exception","errorClass":"ProjectDefinitionError","httpStatus":null,"severity":"error","filePath":"lib/crewai-core/src/crewai_core/project.py","lineNumber":127,"sourceCode":"\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\n\n    if not resolved_candidate.is_relative_to(root):\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must resolve inside the project root; \"\n            f\"got {definition!r}.\"\n        )\n\n    if not resolved_candidate.exists():\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must point to an existing file; \"\n            f\"got {definition!r}.\"\n        )\n\n    if not resolved_candidate.is_file():\n        raise ProjectDefinitionError(\n            \"[tool.crewai] definition must point to a regular file; \"","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-core/src/crewai_core/project.py#L109-L145","documentation":"Raised when Path.resolve(strict=False) on (root / definition) raises OSError. This means combining the definition with the project root produced a path the OS refused to resolve — typically an embedded NUL byte, a path component that is too long, or a symlink loop inside the definition path. Distinct from a missing file (that is handled later); this is a structurally invalid path string.","triggerScenarios":"Passing a definition containing a NUL character, a component exceeding filesystem NAME_MAX, or a symlink cycle such as definition = \"link/loop/main.py\" where link points back into itself.","commonSituations":"Definition strings built programmatically from user input or network data that embedded control characters; deeply nested generated paths that exceed PATH_MAX; symlink loops created by setup scripts.","solutions":["Sanitize the definition string: strip control characters (especially \\\\x00) and validate components are reasonable lengths.","Inspect the resolved candidate path manually in a REPL to find which component fails: (Path(root) / definition).resolve(strict=False).","Remove or fix symlink loops inside the project tree."],"exampleFix":"# before\ndefinition = user_supplied_value  # may contain junk\n\n# after\nimport re\nclean = re.sub(r\"[\\\\x00-\\\\x1f]\", \"\", user_supplied_value).strip(\"/\\\\\")\ndefinition = clean","handlingStrategy":"validation","validationCode":"from pathlib import PurePosixPath\n\ndef clean_definition(definition: str) -> str:\n    return definition.replace(\"\\\\x00\", \"\").strip()","typeGuard":null,"tryCatchPattern":"except ProjectDefinitionError as e:\n    print(f\"Unresolvable definition path: {e}\")  # inspect OSError detail chained in __cause__","preventionTips":["Sanitize user-provided path strings for control characters before persisting them to config.","Avoid path components near NAME_MAX (255) and symlink cycles in project trees."],"tags":["filesystem","input-sanitization","path-validation"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}