gohugoio/hugo · warning

the %s gem is not installed

Error message

the %s gem is not installed

What it means

In `CanRenderGoATDiagrams()`, Hugo runs `gem list asciidoctor-diagram --installed` through its sandboxed exec (`hexec`); a non-zero exit means the `asciidoctor-diagram` gem — required for rendering GoAT/ASCII-art diagrams in AsciiDoc content — is not installed, and this error is returned. The format arg is the extension name constant (`asciidoctor-diagram`).

Source

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

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

	// 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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install the gem: `gem install asciidoctor-diagram`, then verify with `gem list asciidoctor-diagram --installed`.
2. If using rbenv/rvm/asdf, ensure the active Ruby matches the one whose `gem` is on PATH (`gem env` vs `which asciidoctor`).
3. In CI, add the gem install step to the image or pipeline before the Hugo build/tests.

Example fix

# before
gem install asciidoctor
# after
gem install asciidoctor asciidoctor-diagram

out, err := exec.Command("gem", "list", "--local", "asciidoctor-diagram").Output()
if err != nil || !strings.Contains(string(out), "asciidoctor-diagram") {
    return errors.New("required gem not installed")
}

When it happens

Trigger: `CanRenderGoATDiagrams()` executing where `asciidoctor` and `gem` exist but `gem list asciidoctor-diagram --installed` exits non-zero (gem absent, or installed under a different Ruby than the `gem` on PATH).

Common situations: Installing asciidoctor but forgetting its diagram extension, multiple Ruby versions where the gem landed in a different gemset (rbenv/rvm mismatch), or CI images that include asciidoctor but not optional gems. Seen when enabling `asciidoctor-diagram` in `markup.asciidocext.extensions` or running Hugo's diagram tests.

Related errors

• the RubyGems CLI (%s) is not installed
• the AsciiDoc converter (%s) is not installed
• the GoAT CLI (%s) 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/8d93869404c620f2.json. Report an issue: GitHub ↗.