crewAIInc/crewAI · error · ProjectDefinitionError

Invalid [tool.crewai] definition path

Error message

Invalid [tool.crewai] definition path {definition!r}: {exc}

What it means

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.

Solutions

  1. Sanitize the definition string: strip control characters (especially \\x00) and validate components are reasonable lengths.
  2. Inspect the resolved candidate path manually in a REPL to find which component fails: (Path(root) / definition).resolve(strict=False).
  3. Remove or fix symlink loops inside the project tree.

Example fix

# before
definition = user_supplied_value  # may contain junk

# after
import re
clean = re.sub(r"[\\x00-\\x1f]", "", user_supplied_value).strip("/\\")
definition = clean
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import PurePosixPath

def clean_definition(definition: str) -> str:
    return definition.replace("\\x00", "").strip()

Try / catch

except ProjectDefinitionError as e:
    print(f"Unresolvable definition path: {e}")  # inspect OSError detail chained in __cause__

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/b8372a18201227bc. Report an issue: GitHub.

Appendix: source

Thrown at lib/crewai-core/src/crewai_core/project.py:127

    if definition_path.is_absolute() or windows_definition_path.is_absolute():
        raise ProjectDefinitionError(
            "[tool.crewai] definition must be relative to the project root; "
            f"got {definition!r}."
        )

    try:
        root = root_path.resolve(strict=True)
    except OSError as exc:
        raise ProjectDefinitionError(
            f"Invalid project root for [tool.crewai] definition: {exc}"
        ) from exc

    candidate = root / definition_path
    try:
        resolved_candidate = candidate.resolve(strict=False)
    except OSError as exc:
        raise ProjectDefinitionError(
            f"Invalid [tool.crewai] definition path {definition!r}: {exc}"
        ) from exc

    if not resolved_candidate.is_relative_to(root):
        raise ProjectDefinitionError(
            "[tool.crewai] definition must resolve inside the project root; "
            f"got {definition!r}."
        )

    if not resolved_candidate.exists():
        raise ProjectDefinitionError(
            "[tool.crewai] definition must point to an existing file; "
            f"got {definition!r}."
        )

    if not resolved_candidate.is_file():
        raise ProjectDefinitionError(
            "[tool.crewai] definition must point to a regular file; "

View on GitHub (pinned to 754d7323be)