Troubleshooting

414 URI Too Long

By default, the extension retrieves images from the Kroki server using GET requests. If the requested URI exceeds the maximum length the server can process, the server returns a 414 Request-URI Too Long error. The default maximum URI length on the public Kroki server is 4096 characters.

To resolve this issue, choose one of the following approaches:

Increase the max URI length on a self-hosted Kroki instance.
See the Kroki configuration documentation.
Switch to POST requests by enabling kroki-fetch-diagram and setting kroki-http-method to adaptive or post:
```
:kroki-fetch-diagram: true
:kroki-http-method: post
```

Setting kroki-http-method alone is not enough: without kroki-fetch-diagram, the generated HTML references the image with a GET URL, and the request sent by the browser would still be too long. When using POST requests, the extension downloads images from the server and stores them locally. The images are then referenced using a relative path rather than a direct link to the Kroki server.

Diagram rendering failures

When a diagram cannot be converted — for example, the Kroki server is unreachable or a referenced diagram file does not exist — the document conversion does not fail. Instead, the extension logs a warning (Skipping <type> block: <reason>) and renders the diagram source as-is. The kroki-error CSS class is added to the resulting block so failed diagrams can be styled or located in the output.