{"record":{"id":"4e3bf80c569f257a","repo":"apache/beam","slug":"unable-to-draw-pipeline-graphviz-library-missing","errorCode":null,"errorMessage":"Unable to draw pipeline. graphviz library missing.","messagePattern":"Unable to draw pipeline\\. graphviz library missing\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"sdks/python/apache_beam/runners/portability/fn_api_runner/visualization_tools.py","lineNumber":30,"sourceCode":"# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n#\n\n\"\"\"Set of utilities to visualize a pipeline to be executed by FnApiRunner.\"\"\"\n\nfrom apache_beam.runners.portability.fn_api_runner.translations import Stage\nfrom apache_beam.runners.portability.fn_api_runner.watermark_manager import WatermarkManager\nfrom apache_beam.utils import timestamp\n\n\ndef show_stage(stage: Stage):\n  try:\n    import graphviz\n  except ImportError:\n    import warnings\n    warnings.warn('Unable to draw pipeline. graphviz library missing.')\n    return\n\n  g = graphviz.Digraph()\n\n  seen_pcollections = set()\n  for t in stage.transforms:\n    g.node(t.unique_name, shape='box')\n\n    for i in t.inputs.values():\n      assert isinstance(i, str)\n      if i not in seen_pcollections:\n        g.node(i)\n        seen_pcollections.add(i)\n\n      g.edge(i, t.unique_name)\n\n    for o in t.outputs.values():\n      assert isinstance(o, str)","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/fn_api_runner/visualization_tools.py#L12-L48","documentation":"show_stage in visualization_tools renders a single fn_api_runner Stage as a graphviz Digraph. If the optional 'graphviz' package is not installed, the import fails and the function warns 'Unable to draw pipeline. graphviz library missing.' and returns instead of rendering anything.","triggerScenarios":"Calling show_stage(stage) (e.g. while debugging an FnApiRunner pipeline with environment='LOOPBACK' or via instrumentation helpers) without the graphviz Python package installed.","commonSituations":"Local debugging of portable pipelines; the graphviz extra was never installed because it's optional for normal runs.","solutions":["pip install graphviz (and ensure the graphviz system binaries are on PATH, e.g. apt install graphviz / brew install graphviz).","Re-run the visualization after installation; the stage drawing will then render.","If visualization is not needed, ignore the warning or guard calls with a check for the module."],"exampleFix":"# before\nshow_stage(stage)  # warns, draws nothing\n# after\npip install graphviz  # shell\nshow_stage(stage)     # renders Digraph","handlingStrategy":"fallback","validationCode":"try:\n    import graphviz  # noqa: F401\n    GRAPHVIZ_OK = True\nexcept ImportError:\n    GRAPHVIZ_OK = False","typeGuard":null,"tryCatchPattern":"if GRAPHVIZ_OK:\n    show_stage(stage)\nelse:\n    print('graphviz unavailable; skipping stage visualization')","preventionTips":["Include graphviz (Python package + system binaries) in dev/debug images","Check optional deps before enabling visualization tooling","Document graphviz as a requirement for pipeline debugging workflows"],"tags":["visualization","missing-dependency","graphviz","debugging"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}