crewAIInc/crewAI · error · SystemExit

An unexpected error occurred while running the declarative f

Error message

An unexpected error occurred while running the declarative flow: {e}

What it means

Catch-all around the subprocess that re-executes a declarative flow (subprocess.run, check=True, custom env). CalledProcessError is mapped to the child's exit code first; this handler catches everything else — almost always failure to spawn the subprocess executable (FileNotFoundError/OSError) or an invalid env mapping. Message goes to stderr and the process exits 1.

Source

Thrown at lib/cli/src/crewai_cli/run_declarative_flow.py:486

def _execute_declarative_flow_command(command: list[str]) -> None:
    env = build_env_with_all_tool_credentials()

    try:
        subprocess.run(  # noqa: S603
            command,
            capture_output=False,
            text=True,
            check=True,
            env=env,
        )
    except subprocess.CalledProcessError as e:
        raise SystemExit(e.returncode) from e
    except Exception as e:
        click.echo(
            f"An unexpected error occurred while running the declarative flow: {e}",
            err=True,
        )
        raise SystemExit(1) from e


def is_declarative_flow_project_env() -> bool:
    import os

    return os.environ.get("UV_RUN_RECURSION_DEPTH") is not None


def _has_project_file(project_root: Path | None = None) -> bool:
    root = project_root or Path.cwd()
    return (root / "pyproject.toml").is_file()


def _format_result(result: Any) -> str:
    raw_result = getattr(result, "raw", result)
    if isinstance(raw_result, str):
        return raw_result

View on GitHub (pinned to 754d7323be)

Solutions

1. Read the exception text; 'No such file or directory' → install the missing runner (usually `uv`: `pip install uv` or the standalone installer) or fix PATH.
2. Verify `uv --version` (or the relevant runner) works in the same shell/environment.
3. If you wrap the CLI with a custom environment, keep PATH intact and use only string env values.
4. For process-limit failures, reduce parallelism on the agent.

Example fix

# before
$ crewai flow run   # container without uv
# An unexpected error occurred while running the declarative flow: [Errno 2] No such file or directory: 'uv'

# after
$ pip install uv
$ crewai flow run

import shutil

if shutil.which("uv") is None:  # the runner the CLI re-executes through
    raise SystemExit("uv not on PATH; install it before running declarative flows")

try:
    run_declarative_flow(...)
except SystemExit as e:
    if e.code not in (0, None):
        logging.error("declarative flow run failed (exit=%s)", e.code)
    raise

When it happens

Trigger: The re-exec command (typically via uv/python) not found on PATH in the constructed `env`; env values that are not strings (TypeError); OS-level spawn limits (too many processes) raising OSError.

Common situations: Containers/CI without `uv` installed when the CLI delegates via `uv run`; PATH overridden by wrapper scripts; env var manipulation injecting None; heavily loaded CI agents hitting process limits.

Related errors

• An unexpected error occurred: {e}
• An error occurred while plotting the flow: {e}
• An unexpected error occurred while running the JSON crew: {e
• Git is not installed or not found in your PATH.
• An error occurred while running the declarative flow: {exc}

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