{"record":{"id":"3420ba21de51638a","repo":"crewAIInc/crewAI","slug":"an-error-occurred-while-plotting-the-declarative-f","errorCode":null,"errorMessage":"An error occurred while plotting the declarative flow: {exc}","messagePattern":"An error occurred while plotting the declarative flow: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"lib/cli/src/crewai_cli/run_declarative_flow.py","lineNumber":408,"sourceCode":"        try:\n            return float(raw)\n        except ValueError:\n            return raw\n    if field_type == \"boolean\":\n        return raw.strip().lower() in {\"1\", \"true\", \"yes\", \"y\", \"on\"}\n    return raw\n\n\ndef plot_declarative_flow(definition: str | Path) -> None:\n    \"\"\"Plot a declarative flow from a definition path.\"\"\"\n    try:\n        flow = load_declarative_flow(definition)\n        flow.plot()\n    except Exception as exc:\n        click.echo(\n            f\"An error occurred while plotting the declarative flow: {exc}\", err=True\n        )\n        raise SystemExit(1) from exc\n\n\ndef load_declarative_flow(definition: str | Path) -> Any:\n    \"\"\"Load a declarative Flow instance from a definition path.\"\"\"\n    try:\n        from crewai.flow.flow import Flow\n    except ImportError as exc:\n        click.echo(\n            \"Running declarative flows requires the full crewai package.\",\n            err=True,\n        )\n        raise SystemExit(1) from exc\n\n    definition_path = Path(definition).expanduser()\n    try:\n        if not definition_path.is_file():\n            if definition_path.exists():\n                click.echo(","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/cli/src/crewai_cli/run_declarative_flow.py#L390-L426","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\n$ crewai flow plot --definition flow.yaml\n# An error occurred while plotting the declarative flow: `dot` not found in path\n\n# after\n$ sudo apt-get install graphviz   # or: brew install graphviz\n$ crewai flow plot --definition flow.yaml","handlingStrategy":"try-catch","validationCode":"import shutil\n\nif shutil.which(\"dot\") is None:\n    raise SystemExit(\"graphviz 'dot' binary missing; install graphviz before plotting\")","typeGuard":null,"tryCatchPattern":"try:\n    flow = load_declarative_flow(path)\n    flow.plot()\nexcept SystemExit:\n    raise\nexcept Exception as exc:\n    logging.exception(\"declarative flow plot failed\")  # keep full traceback\n    raise SystemExit(1) from exc","preventionTips":["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."],"tags":["flow","plotting","graphviz","declarative","cli"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}