crewAIInc/crewAI · error · ProjectDefinitionError

[tool.crewai] definition must be relative to the project roo

Error message

[tool.crewai] definition must be relative to the project root; got {definition!r}.

What it means

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.

Source

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

        )

    return resolve_project_definition_path(definition=definition, project_root=root)


def resolve_project_definition_path(definition: str, project_root: Path | str) -> Path:
    """Resolve a ``[tool.crewai].definition`` path inside ``project_root``."""
    root_path = Path(project_root)
    definition_path = Path(definition)
    windows_definition_path = PureWindowsPath(definition)

    if definition.startswith("~"):
        raise ProjectDefinitionError(
            "[tool.crewai] definition must be a project-local path; "
            f"got {definition!r}."
        )

    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

View on GitHub (pinned to 754d7323be)

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.

Example fix

# before
[tool.crewai]
definition = "/opt/crews/sales/main.py"

# after
[tool.crewai]
definition = "src/sales/main.py"

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path, PureWindowsPath

def is_relative_definition(definition: str) -> bool:
    return not Path(definition).is_absolute() and not PureWindowsPath(definition).is_absolute()

Try / catch

except ProjectDefinitionError as e:
    # message contains 'must be relative to the project root'
    raise ConfigError(str(e)) from e

Prevention

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 '~'.

When it happens

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

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

Related errors

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