crewAIInc/crewAI · error · SystemExit

An error occurred while running the declarative flow: {exc}

Error message

An error occurred while running the declarative flow: {exc}

What it means

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.

Source

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

    # The TUI is the interactive default. Headless contexts run directly on the
    # terminal: deploy/CREWAI_DMN, piped output, CI — anything without an
    # interactive TTY. is_interactive() already folds in the CREWAI_DMN check.
    # Human-feedback flows also run on the terminal: their methods collect input
    # via the flow runtime's blocking input()/Rich prompts (and async feedback
    # returns a pending marker rather than completing), neither of which the
    # Textual TUI can handle correctly.
    if is_interactive() and not _flow_uses_human_feedback(flow):
        _run_declarative_flow_tui(flow, resolved_inputs or None)
        return

    try:
        result = flow.kickoff(inputs=resolved_inputs or None)
    except Exception as exc:
        click.echo(
            f"An error occurred while running the declarative flow: {exc}",
            err=True,
        )
        raise SystemExit(1) from exc
    click.echo(_format_result(result))


def _run_declarative_flow_tui(
    flow: Flow[Any], resolved_inputs: dict[str, Any] | None
) -> Any:
    """Run a declarative flow on the CrewAI TUI (the interactive default).

    Mirrors the declarative-crew TUI contract (``run_crew._run_json_crew``):
    a failed flow exits non-zero, a user quit ends the process so in-flight LLM
    work stops, and choosing Deploy chains into the deploy command.
    """
    import os
    import sys

    from crewai.events.event_listener import EventListener

    from crewai_cli.crew_run_tui import CrewRunApp

View on GitHub (pinned to 754d7323be)

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.

Example fix

# before
$ crewai flow run  # in CI
# An error occurred while running the declarative flow: Error code: 401 - Incorrect API key

# after
$ export OPENAI_API_KEY=sk-...
$ crewai flow run

Defensive patterns

Strategy: try-catch

Validate before calling

# Preflight the usual kickoff failure causes before running
import os
required_keys = ["OPENAI_API_KEY"]  # keys your flow's LLM needs
missing = [k for k in required_keys if not os.environ.get(k)]
if missing:
    raise SystemExit(f"missing env vars: {missing}")

Try / catch

try:
    result = flow.kickoff(inputs=resolved_inputs)
except Exception as exc:
    logging.exception("flow kickoff failed")  # keep the full traceback
    raise SystemExit(1) from exc

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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