crewAIInc/crewAI · error · ProjectDefinitionError

[tool.crewai] definition must be a string project-local path

Error message

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

What it means

Error "[tool.crewai] definition must be a string project-local path; got {raw_definition!r}." thrown in crewAIInc/crewAI.

Source

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

    """Return a configured CrewAI definition path for a project type.

    ``[tool.crewai].type`` must match ``project_type`` and ``definition`` must
    be a non-empty project-local file path. Missing definitions return ``None``
    so callers can fall back to legacy entrypoints for that project type.
    """
    root = Path(project_root) if project_root is not None else Path.cwd()
    if pyproject_data is None:
        pyproject_data = read_toml(root / "pyproject.toml")

    crewai_config = get_crewai_project_config(pyproject_data)
    if crewai_config.get("type") != project_type:
        return None

    if "definition" not in crewai_config:
        return None
    raw_definition = crewai_config["definition"]
    if not isinstance(raw_definition, str):
        raise ProjectDefinitionError(
            "[tool.crewai] definition must be a string project-local path; "
            f"got {raw_definition!r}."
        )

    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)

View on GitHub (pinned to 754d7323be)

Solutions

1. Set [tool.crewai].definition in pyproject.toml to a string path relative to the project root, e.g. definition = "crew.json".
2. Remove non-string values from the definition setting.

When it happens

Trigger: Thrown at lib/crewai-core/src/crewai_core/project.py:84 when the library encounters an invalid state.

Common situations: Occurs when [tool.crewai] definition in pyproject.toml is not a string. Set it to a string path relative to the project root.

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