Unable to draw pipeline. graphviz library missing.

Error message

Unable to draw pipeline. graphviz library missing.

What it means

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.

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.

Example fix

# before
show_stage(stage)  # warns, draws nothing
# after
pip install graphviz  # shell
show_stage(stage)     # renders Digraph

Defensive patterns

Strategy: fallback

Validate before calling

try:
    import graphviz  # noqa: F401
    GRAPHVIZ_OK = True
except ImportError:
    GRAPHVIZ_OK = False

Try / catch

if GRAPHVIZ_OK:
    show_stage(stage)
else:
    print('graphviz unavailable; skipping stage visualization')

Prevention

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

When it happens

Trigger: Calling show_stage(stage) (e.g. while debugging an FnApiRunner pipeline with environment='LOOPBACK' or via instrumentation helpers) without the graphviz Python package installed.

Common situations: Local debugging of portable pipelines; the graphviz extra was never installed because it's optional for normal runs.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/4e3bf80c569f257a. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/fn_api_runner/visualization_tools.py:30

# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

"""Set of utilities to visualize a pipeline to be executed by FnApiRunner."""

from apache_beam.runners.portability.fn_api_runner.translations import Stage
from apache_beam.runners.portability.fn_api_runner.watermark_manager import WatermarkManager
from apache_beam.utils import timestamp


def show_stage(stage: Stage):
  try:
    import graphviz
  except ImportError:
    import warnings
    warnings.warn('Unable to draw pipeline. graphviz library missing.')
    return

  g = graphviz.Digraph()

  seen_pcollections = set()
  for t in stage.transforms:
    g.node(t.unique_name, shape='box')

    for i in t.inputs.values():
      assert isinstance(i, str)
      if i not in seen_pcollections:
        g.node(i)
        seen_pcollections.add(i)

      g.edge(i, t.unique_name)

    for o in t.outputs.values():
      assert isinstance(o, str)

View on GitHub (pinned to 12126d8942)