crewAIInc/crewAI · error · SystemExit

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

Error message

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

What it means

Catch-all around plot_declarative_flow(): either load_declarative_flow(definition) (parsing/loading the definition file) or flow.plot() (rendering) raised an unexpected exception that escaped their own targeted handlers (load_declarative_flow handles ImportError, path errors, and OSError/UnicodeError/ValueError/ValidationError itself). The CLI echoes the message to stderr and exits 1.

Source

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

        try:
            return float(raw)
        except ValueError:
            return raw
    if field_type == "boolean":
        return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
    return raw


def plot_declarative_flow(definition: str | Path) -> None:
    """Plot a declarative flow from a definition path."""
    try:
        flow = load_declarative_flow(definition)
        flow.plot()
    except Exception as exc:
        click.echo(
            f"An error occurred while plotting the declarative flow: {exc}", err=True
        )
        raise SystemExit(1) from exc


def load_declarative_flow(definition: str | Path) -> Any:
    """Load a declarative Flow instance from a definition path."""
    try:
        from crewai.flow.flow import Flow
    except ImportError as exc:
        click.echo(
            "Running declarative flows requires the full crewai package.",
            err=True,
        )
        raise SystemExit(1) from exc

    definition_path = Path(definition).expanduser()
    try:
        if not definition_path.is_file():
            if definition_path.exists():
                click.echo(

View on GitHub (pinned to 754d7323be)

Solutions

Read the exception text — 'dot' / graphviz messages mean installing Graphviz (`apt install graphviz` / `brew install graphviz`) fixes it.
Ensure the working directory is writable since the plot file is written to cwd/output.
If it's a definition-content error, the message usually names the bad key/step; fix the definition and confirm with `crewai flow run` dry checks.
Retry after fixing; if opaque, load the flow in a Python REPL and call flow.plot() directly for a full traceback.

Example fix

# before
$ crewai flow plot --definition flow.yaml
# An error occurred while plotting the declarative flow: `dot` not found in path

# after
$ sudo apt-get install graphviz   # or: brew install graphviz
$ crewai flow plot --definition flow.yaml

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil

if shutil.which("dot") is None:
    raise SystemExit("graphviz 'dot' binary missing; install graphviz before plotting")

Try / catch

try:
    flow = load_declarative_flow(path)
    flow.plot()
except SystemExit:
    raise
except Exception as exc:
    logging.exception("declarative flow plot failed")  # keep full traceback
    raise SystemExit(1) from exc

Prevention

Install graphviz (binary, not just the Python package) on any machine that runs `crewai flow plot`.
Ensure the output directory is writable before plotting.
Smoke-test plotting right after scaffold so environment gaps surface early.

When it happens

Trigger: Graphviz/dot issues in flow.plot() (e.g. the `dot` binary missing or a pydot/graphviz import error other than ImportError); errors raised while writing the output plot file (permission denied on the output path); definition content that parses but builds an invalid Flow object (e.g. unknown step reference surfacing as KeyError/AttributeError).

Common situations: Fresh machines without graphviz installed when first running `crewai flow plot`; read-only working directories; declarative definitions referencing methods/steps that don't resolve at plot time.

Related errors

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