crewAIInc/crewAI · error · ProjectDefinitionError

[tool.crewai] definition must be a project-local path; got {

Error message

[tool.crewai] definition must be a project-local path; got {definition!r}.

What it means

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.

Source

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

        )

    definition = raw_definition.strip()
    if not definition:
        raise ProjectDefinitionError(
            "[tool.crewai] definition must be a non-empty project-local path."
        )

    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

View on GitHub (pinned to 754d7323be)

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.

Example fix

# before
[tool.crewai]
definition = "~/crews/my_crew/main.py"

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

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def definition_ok(definition: str) -> bool:
    return not definition.startswith("~")

Try / catch

from crewai_core.project import ProjectDefinitionError
try:
    path = resolve_project_definition_path(definition, root)
except ProjectDefinitionError as e:
    print(f"Bad [tool.crewai] definition config: {e}")

Prevention

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.

When it happens

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

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

Related errors

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