crewAIInc/crewAI · error · ValueError

project_name is required to create a ZIP deployment

Error message

project_name is required to create a ZIP deployment

What it means

Raised by the project-config loader when [tool.crewai].definition is a string but strips to empty (only whitespace). The loader normalizes then rejects empty definitions with ProjectDefinitionError, since an empty path cannot resolve to a project definition file.

Source

Thrown at lib/cli/src/crewai_cli/deploy/main.py:461

            console.print(
                "Could not create an initial Git commit. "
                "Continuing with ZIP deployment using Git file listing.",
                style="yellow",
            )
            console.print(str(commit_error), style="dim")
            return repository

        return repository

    def _create_crew_from_zip(
        self,
        env_vars: dict[str, str],
        repository: git.Repository | None,
        confirm: bool,
    ) -> Any:
        """Create a deployment by uploading a project ZIP archive."""
        if not self.project_name:
            raise ValueError("project_name is required to create a ZIP deployment")

        console.print("Preparing project ZIP...", style="bold blue")
        zip_file_path = create_project_zip(self.project_name, repository=repository)
        try:
            self._confirm_zip_input(env_vars, confirm)
            console.print("Uploading project ZIP...", style="bold blue")
            return self.plus_api_client.create_crew_from_zip(
                zip_file_path,
                name=self.project_name,
                env=env_vars,
            )
        finally:
            zip_file_path.unlink(missing_ok=True)

    def _update_crew_from_zip(
        self,
        uuid: str,
        repository: git.Repository | None,

View on GitHub (pinned to 754d7323be)

Solutions

1. Set definition to the real project-local path of your definition file (e.g. "src/my_project/definitions.py")
2. If the key is not needed yet, remove the definition key entirely — the loader returns None when it is absent
3. Ensure the path is project-local and resolvable from the project root
4. Re-run the loader to verify resolution succeeds

Example fix

# before
[tool.crewai]
type = "crew"
definition = ""

# after
[tool.crewai]
type = "crew"
definition = "src/my_project/definitions.py"

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)
defn = data.get("tool", {}).get("crewai", {}).get("definition")
assert defn is None or defn.strip(), "[tool.crewai].definition must be a non-empty path"

from crewai_core.project import ProjectDefinitionError

try:
    path = load_project_definition(project_root=".")
except ProjectDefinitionError as e:
    raise SystemExit(f"Invalid pyproject.toml: {e}") from e

When it happens

Trigger: pyproject.toml contains definition = "" or definition = " " (whitespace-only) under [tool.crewai] while the type matches the requested project type.

Common situations: Placeholder value committed during scaffolding, template left with empty quotes, or automated config generation writing an empty string.

Related errors

• No JSON crew definition configured in [tool.crewai].definiti
• Project name cannot be empty
• Project name '{name}' produces invalid folder name '{folder_
• No deployable project files were found.
• Missing required fields in OAuth2 configuration: [{', '.join

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