crewAIInc/crewAI · error · SystemExit

An error occurred while plotting the flow: {e}

Error message

An error occurred while plotting the flow: {e}

What it means

Printed by the plot-flow command when the underlying `uv run plot` subprocess exits non-zero (CalledProcessError) and no declarative flow definition was found via configured_project_declarative_flow(). The message embeds the exit code and the failing command; the CLI then exits 1. The actual plotting failure happened inside the project's own plot task, and this is the wrapper reporting it.

Source

Thrown at lib/cli/src/crewai_cli/plot_flow.py:27

    """
    from crewai_cli.run_declarative_flow import (
        configured_project_declarative_flow,
        plot_declarative_flow_in_project_env,
    )

    if definition := configured_project_declarative_flow():
        plot_declarative_flow_in_project_env(definition)
    else:
        command = ["uv", "run", "plot"]

        try:
            subprocess.run(  # noqa: S603
                command, capture_output=False, text=True, check=True
            )

        except subprocess.CalledProcessError as e:
            click.echo(f"An error occurred while plotting the flow: {e}", err=True)
            raise SystemExit(1) from e

        except Exception as e:
            click.echo(f"An unexpected error occurred: {e}", err=True)
            raise SystemExit(1) from e

View on GitHub (pinned to 754d7323be)

Solutions

  1. Run `uv run plot` directly to see the full traceback the wrapper hides
  2. Install graphviz system package if the error mentions dot/graphviz (apt-get install graphviz / brew install graphviz)
  3. Fix import-time errors in your flow module (missing env vars, typos) exposed by the plot task
  4. Ensure the project defines the plot command/task in pyproject.toml [tool.crewai] or the uv task list

Example fix

# before
crewai plot-flow  # An error occurred while plotting the flow: ... exit 1
# after (debug directly, fix cause, re-run)
uv run plot
crewai plot-flow
Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, subprocess

def plot_prereqs_ok(project_dir: str = ".") -> bool:
    has_dot = shutil.which("dot") is not None  # graphviz
    has_task = subprocess.run(
        ["uv", "run", "plot", "--help"], cwd=project_dir, capture_output=True
    ).returncode == 0
    return has_dot and has_task

Try / catch

try:
    plot_flow()
except SystemExit:
    # run `uv run plot` manually to surface the real traceback, fix, re-run
    raise

Prevention

When it happens

Trigger: Running `crewai plot-flow` (or plot_flow()) in a project where `uv run plot` fails: no plot script/task defined in pyproject.toml, missing graphviz system dependency, import errors in the flow module (e.g. undefined LLM env vars), or the flow class failing to instantiate for graph construction.

Common situations: Fresh projects without the plot task wired into uv; graphviz not installed (dot binary missing) so diagram export crashes; flows importing API keys at module load that are absent; syntax/import errors introduced in flow code that only surface when the graph builder imports it.

Related errors

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