{"record":{"id":"0383ad2ab78f84d5","repo":"crewAIInc/crewAI","slug":"an-unexpected-error-occurred-while-running-the-dec","errorCode":null,"errorMessage":"An unexpected error occurred while running the declarative flow: {e}","messagePattern":"An unexpected error occurred while running the declarative flow: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/run_declarative_flow.py","lineNumber":486,"sourceCode":"def _execute_declarative_flow_command(command: list[str]) -> None:\n    env = build_env_with_all_tool_credentials()\n\n    try:\n        subprocess.run(  # noqa: S603\n            command,\n            capture_output=False,\n            text=True,\n            check=True,\n            env=env,\n        )\n    except subprocess.CalledProcessError as e:\n        raise SystemExit(e.returncode) from e\n    except Exception as e:\n        click.echo(\n            f\"An unexpected error occurred while running the declarative flow: {e}\",\n            err=True,\n        )\n        raise SystemExit(1) from e\n\n\ndef is_declarative_flow_project_env() -> bool:\n    import os\n\n    return os.environ.get(\"UV_RUN_RECURSION_DEPTH\") is not None\n\n\ndef _has_project_file(project_root: Path | None = None) -> bool:\n    root = project_root or Path.cwd()\n    return (root / \"pyproject.toml\").is_file()\n\n\ndef _format_result(result: Any) -> str:\n    raw_result = getattr(result, \"raw\", result)\n    if isinstance(raw_result, str):\n        return raw_result\n","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L468-L504","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify `uv --version` (or the relevant runner) works in the same shell/environment.","If you wrap the CLI with a custom environment, keep PATH intact and use only string env values.","For process-limit failures, reduce parallelism on the agent."],"exampleFix":"# before\n$ crewai flow run   # container without uv\n# An unexpected error occurred while running the declarative flow: [Errno 2] No such file or directory: 'uv'\n\n# after\n$ pip install uv\n$ crewai flow run","handlingStrategy":"try-catch","validationCode":"import shutil\n\nif shutil.which(\"uv\") is None:  # the runner the CLI re-executes through\n    raise SystemExit(\"uv not on PATH; install it before running declarative flows\")","typeGuard":null,"tryCatchPattern":"try:\n    run_declarative_flow(...)\nexcept SystemExit as e:\n    if e.code not in (0, None):\n        logging.error(\"declarative flow run failed (exit=%s)\", e.code)\n    raise","preventionTips":["Include uv in container images that run `crewai flow` commands.","Preserve PATH when customizing the subprocess environment.","Preflight `uv --version` in CI before flow steps to fail with an actionable message."],"tags":["subprocess","flow","environment","uv","cli"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}