gohugoio/hugo · warning

the GoAT CLI (%s) is not installed

Error message

the GoAT CLI (%s) is not installed

What it means

The last check in `CanRenderGoATDiagrams()`: the `asciidoctor-diagram` extension delegates GoAT (Go ASCII Tool) diagram rendering to an external `goat` executable, and Hugo verifies it is in `$PATH`. Without it, AsciiDoc GoAT diagram blocks cannot be rendered even though asciidoctor and the diagram gem are present.

Source

Thrown at markup/asciidocext/internal/converter.go:300

	// Verify that the required AsciiDoc converter extension is installed.
	sc := security.DefaultConfig
	sc.Exec.Allow = security.MustNewWhitelist(gemBinaryName)
	ex := hexec.New(sc, "", loggers.NewDefault())

	args := []any{"list", asciiDocDiagramExtension, "--installed"}
	cmd, err := ex.New(gemBinaryName, args...)
	if err != nil {
		return false, err
	}
	err = cmd.Run()
	if err != nil {
		return false, fmt.Errorf("the %s gem is not installed", asciiDocDiagramExtension)
	}

	// Verify that the GoAT CLI is installed.
	if !hexec.InPath(goatBinaryName) {
		return false, fmt.Errorf("the GoAT CLI (%s) is not installed", goatBinaryName)
	}

	return true, nil
}

// extractTOC extracts the toc from the given src html.
// It returns the html without the TOC, and the TOC data
func (a *AsciiDocConverter) extractTOC(src []byte) ([]byte, *tableofcontents.Fragments, error) {
	var buf bytes.Buffer
	buf.Write(src)
	node, err := html.Parse(&buf)
	if err != nil {
		return nil, nil, err
	}
	var (
		f       func(*html.Node) bool
		toc     *tableofcontents.Fragments
		toVisit []*html.Node

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install the GoAT CLI: `go install github.com/blampe/goat/cmd/goat@latest`.
2. Ensure `$GOPATH/bin` (or `$HOME/go/bin`) is on `$PATH`; verify with `which goat`.
3. If GoAT diagrams aren't needed, ignore — this only gates the diagram-rendering capability/tests.

Example fix

# before: goat missing
# after
go install github.com/blampe/goat/cmd/goat@latest
export PATH="$HOME/go/bin:$PATH"

if _, err := exec.LookPath("goat"); err != nil {
    return fmt.Errorf("GoAT CLI missing: %w", err)
}

When it happens

Trigger: `CanRenderGoATDiagrams()` running where asciidoctor, gem, and the asciidoctor-diagram gem all check out but no `goat` binary is resolvable in `$PATH`.

Common situations: Hugo contributors running the asciidocext test suite; users setting up GoAT diagrams in AsciiDoc content who installed the Ruby side but not the Go-based `goat` CLI, or installed it to `$GOPATH/bin` without adding that to PATH.

Related errors

• the AsciiDoc converter (%s) is not installed
• the RubyGems CLI (%s) is not installed
• the %s gem is not installed
• asciidoctor not found in $PATH, cannot render %q
• language %q not found

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/8b23d7751b660f3d.json. Report an issue: GitHub ↗.