crewAIInc/crewAI · error · ProjectDefinitionError

[tool.crewai] definition must point to a regular file; got {

Error message

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

What it means

Raised when the definition path exists and passes containment checks but is not a regular file (Path.is_file() is False). Typical culprits: the path points at a directory, a FIFO/socket/device, or (on some platforms) a dangling special entry. The loader needs a readable file, so anything else is rejected with the offending definition value.

Source

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

    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(
    pyproject_path: str, keys: list[str], require: bool
) -> Any | None:
    """Look up a dotted attribute path inside ``pyproject_path``.

    The file must declare ``crewai`` in ``[project].dependencies`` for the
    lookup to succeed (a guard against running these helpers outside a crewai

View on GitHub (pinned to 754d7323be)

Solutions

Point definition at the actual entry file (e.g. src/crew/main.py), not the package directory.
Verify with Path(p).is_file() during setup to catch this before the library does.
If you renamed directories, update the TOML value to include the filename.

Example fix

# before
[tool.crewai]
definition = "src/crew"

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

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

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

Try / catch

except ProjectDefinitionError as e:
    if "regular file" in str(e):
        print("definition must name a file, not a directory or special file")

Prevention

Convention: always end definition with an explicit filename (e.g. main.py).
Add a startup self-test that resolves and is_file()s the definition.

When it happens

Trigger: definition = "src/crew" where that is a package directory; definition pointing at a named pipe created by a test harness; a device file path accidentally stored in the TOML.

Common situations: Users point the definition at the crew package folder instead of its entry module; directory-vs-file confusion after restructuring a flat script into a package.

Related errors

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