{"record":{"id":"45bf4590d1904f59","repo":"crewAIInc/crewAI","slug":"an-error-occurred-while-running-the-declarative-fl","errorCode":null,"errorMessage":"An error occurred while running the declarative flow: {exc}","messagePattern":"An 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":95,"sourceCode":"    # The TUI is the interactive default. Headless contexts run directly on the\n    # terminal: deploy/CREWAI_DMN, piped output, CI — anything without an\n    # interactive TTY. is_interactive() already folds in the CREWAI_DMN check.\n    # Human-feedback flows also run on the terminal: their methods collect input\n    # via the flow runtime's blocking input()/Rich prompts (and async feedback\n    # returns a pending marker rather than completing), neither of which the\n    # Textual TUI can handle correctly.\n    if is_interactive() and not _flow_uses_human_feedback(flow):\n        _run_declarative_flow_tui(flow, resolved_inputs or None)\n        return\n\n    try:\n        result = flow.kickoff(inputs=resolved_inputs or None)\n    except Exception as exc:\n        click.echo(\n            f\"An error occurred while running the declarative flow: {exc}\",\n            err=True,\n        )\n        raise SystemExit(1) from exc\n    click.echo(_format_result(result))\n\n\ndef _run_declarative_flow_tui(\n    flow: Flow[Any], resolved_inputs: dict[str, Any] | None\n) -> Any:\n    \"\"\"Run a declarative flow on the CrewAI TUI (the interactive default).\n\n    Mirrors the declarative-crew TUI contract (``run_crew._run_json_crew``):\n    a failed flow exits non-zero, a user quit ends the process so in-flight LLM\n    work stops, and choosing Deploy chains into the deploy command.\n    \"\"\"\n    import os\n    import sys\n\n    from crewai.events.event_listener import EventListener\n\n    from crewai_cli.crew_run_tui import CrewRunApp","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L77-L113","documentation":"Raised when Flow.kickoff() raises any exception during a non-interactive run of a declarative flow (the interactive/TUI and human-feedback paths take different branches). The CLI echoes the exception message to stderr, chains the original exception, and exits 1. The underlying cause is inside the flow — LLM/agent failures, task exceptions, or bad input state.","triggerScenarios":"Running a declarative flow non-interactively (`crewai flow run` with no TTY, or a flow using human feedback forced down this path) where a listener/method raises: missing API keys, pydantic state validation errors, network failures to the LLM provider, or a referenced task/agent that doesn't exist.","commonSituations":"CI/cron runs of flows (no TTY, so this branch always executes); deploying flows where OPENAI_API_KEY etc. are unset; state model fields receiving wrong types from inputs.","solutions":["Read the exception text after the colon — it is the real flow error (e.g. AuthenticationError, ValidationError).","If it is an API key issue, export the key (or load .env) and re-run.","If it is a state/input type error, fix the input values or the state model to match.","Re-run with the TUI (interactive terminal) or add logging inside the failing flow method to localize the throw."],"exampleFix":"# before\n$ crewai flow run  # in CI\n# An error occurred while running the declarative flow: Error code: 401 - Incorrect API key\n\n# after\n$ export OPENAI_API_KEY=sk-...\n$ crewai flow run","handlingStrategy":"try-catch","validationCode":"# Preflight the usual kickoff failure causes before running\nimport os\nrequired_keys = [\"OPENAI_API_KEY\"]  # keys your flow's LLM needs\nmissing = [k for k in required_keys if not os.environ.get(k)]\nif missing:\n    raise SystemExit(f\"missing env vars: {missing}\")","typeGuard":null,"tryCatchPattern":"try:\n    result = flow.kickoff(inputs=resolved_inputs)\nexcept Exception as exc:\n    logging.exception(\"flow kickoff failed\")  # keep the full traceback\n    raise SystemExit(1) from exc","preventionTips":["Validate state inputs against the flow's state model before kickoff (see error 51).","Set and check provider API keys in the environment for non-interactive runs.","Log flow.kickoff with the full traceback in your own wrapper so the CLI's one-line message isn't your only clue."],"tags":["flow","declarative","runtime","llm","cli"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}