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.
Remedies
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:
[planutml] ---- @startuml !pragma layout smetana ... @enduml ----
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:
[plantuml]
----
@startuml
testdot
@enduml
----This should render a diagram like the following:
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 :
PLANTUML_SECURITY_PROFILE=UNSECURE
After adding this property, restart the IDE.
The test diagram from above renders the path of the dot executable:
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.
Background
See chapter Diagrams in the preview for more information.