crewAIInc/crewAI · error · ProjectDefinitionError

[tool.crewai] definition must point to an existing file; got

Error message

[tool.crewai] definition must point to an existing file; got {definition!r}.

What it means

Raised at the final existence check in resolve_project_definition_path: the definition path resolved cleanly and stayed inside the project root, but resolved_candidate.exists() is False. The file simply is not there — not created yet, deleted, renamed, or misnamed (including case-sensitivity mistakes on case-sensitive filesystems).

Source

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

            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; "
            f"got {definition!r}."
        )

    return resolved_candidate


def _get_nested_value(data: dict[str, Any], keys: list[str]) -> Any:
    return reduce(dict.__getitem__, keys, data)


def _get_project_attribute(

View on GitHub (pinned to 754d7323be)

Solutions

Confirm the exact file exists: ls the resolved path shown in the error relative to the project root.
Fix typos, casing, or the file extension in the definition value.
If the entry file is generated (e.g. by a scaffold command), run that generator before resolving the definition.

Example fix

# before
[tool.crewai]
definition = "src/crew/main.py"  # file is actually crew_setup.py

# after
[tool.crewai]
definition = "src/crew/crew_setup.py"

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def definition_file_exists(definition: str, root: Path) -> bool:
    return (root / definition).is_file()

Try / catch

except ProjectDefinitionError as e:
    if "existing file" in str(e):
        print("Create or fix the path of the crew entry file.")

Prevention

Run the scaffold/generator before resolving the definition.
On case-sensitive CI (Linux), double-check filename casing matches the TOML exactly.

When it happens

Trigger: definition = "src/crew/main.py" when the file was never created, was renamed to crew.py, or the casing differs (Main.py vs main.py on Linux). Also after moving files without updating pyproject.toml.

Common situations: Fresh clones of templates where the entry file must be generated first; refactors that renamed the module; case-mismatch paths that worked on macOS/Windows but fail on Linux CI.

Related errors

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