Could not render diagrams with external helpers

Asciidoctor Diagram adds capabilities to render diagrams in an AsciiDoc document.

To render diagram previews, 'dot' or other helpers need to be in the path or specified as a document attribute. See this guide how to add or enable Kroki.

Symptom: Could not find the 'dot' (or other) executable

When adding a diagram to the AsciiDoc file, the preview doesn’t show the diagram, but an error message like:

Could not find the 'dot' executable in PATH; add it to the PATH or specify its location using the 'graphvizdot' document attribute

Cause: Helper executable not found

When using asciidoctor-diagram, some diagrams will need external helper applications for creating the diagram, like for example, GraphViz.


Remedy 1: Upgrade to the latest AsciiDoc plugin version on Windows

Starting with PlantUML 1.2020.25, PlantUML includes a minimal dot executable for Windows. There is no need to install GraphViz manually anymore. Still, PlantUML will use a locally installed GraphViz version if it finds one.

Users should use plugin version 0.32.8 or later for this.

Remedy 2: Adding executable to PATH or document attribute

Most of the time users can make diagrams work by adding the executable (like GraphViz' dot-executable) to the PATH environment variable.

If this doesn’t work for the user, there are other possibilities depending on the diagram type. PlantUML will search for GraphViz using multiple well-known folders and will look for the executable. If an environment variable GRAPHVIZ_DOT exists, it will use the executable stated there.

If the error message persists, go to the settings of the AsciiDoc plugin, and add it as an attribute. For the error message above the attribute is graphvizdot. The value is the full path including the executable, for example C:\Program Files (x86)\Graphviz2.38\bin\dot.exe

Remedy 3: Use Smetana as layout engine

Users can change the layout engine to Smetana, a port of the dot executable to Java. This can be enabled in the diagram’s source with a pragma prefix:

!pragma layout smetana

Users find more information about Smetana on the PlantUML homepage.

Remedy 4: Use Kroki as a cloud-based renderer for diagrams

This plugin supports Kroki to render diagrams. Kroki is available as a cloud-based service and as a self-hosted service.

Symptom: Could not run dot executable for PlantUML

When adding a diagram to the AsciiDoc file, the preview doesn’t show the diagram, but an error message like:

PlantUML cannot parse result from dot/GraphViz.

Cause: dot not executable for PlantUML

This might be due to a locally installed dot executable that is either not compatible with PlantUML, or the executable can’t be started by PlantUML due to restrictions of the operating system (like a virus scanner or execution prevention program).

Remedy: Identify executable used by PlantUML

To analyze this further, render the following test diagram in the preview by adding the following snippet to an AsciiDoc document:


This should render a diagram like the following:

plantuml ok minimal

Unfortunately, this doesn’t show the dot-executable used for this. To show the executable as well, add a custom property to your IDE via Help  Edit custom properties…​:


After adding this property, restart the IDE.

The test diagram from above renders the path of the dot executable:

plantuml ok extended

This image reports that PlantUML uses an executable from a temporary folder. This the case when PlantUML uses its bundled dot executable on Windows.

With this information at hand, users can determine which executable is used, and which executable should be uninstalled or excluded from execution prevention.

Running the executable from the command line can provide further information about why execution fails.


See chapter Diagrams in the preview for more information.