gohugoio/hugo · warning

the RubyGems CLI (%s) is not installed

Error message

the RubyGems CLI (%s) is not installed

What it means

Part of `CanRenderGoATDiagrams()`: after confirming asciidoctor exists, Hugo checks that the RubyGems CLI (`gem`) is in `$PATH`, because it needs `gem list asciidoctor-diagram --installed` to verify the diagram extension. Without `gem`, the extension check cannot run, so GoAT diagram rendering support cannot be confirmed.

Source

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

// HasAsciiDoc reports whether the AsciiDoc converter is installed.
func HasAsciiDoc() (bool, error) {
	if !hexec.InPath(asciiDocBinaryName) {
		return false, fmt.Errorf("the AsciiDoc converter (%s) is not installed", asciiDocBinaryName)
	}
	return true, nil
}

// CanRenderGoATDiagrams reports whether the AsciiDoc converter can render
// GoAT diagrams. Only used in tests.
func CanRenderGoATDiagrams() (bool, error) {
	// Verify that the AsciiDoc converter is installed.
	if ok, err := HasAsciiDoc(); !ok {
		return false, err
	}

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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install RubyGems (usually bundled with Ruby): `apt install ruby-full` or `brew install ruby`, then verify `gem --version`.
2. Add the Ruby bin directory to `$PATH` for the environment running the tests.
3. If you don't need GoAT diagram tests, ignore it — this check only gates that capability.

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

When it happens

Trigger: `CanRenderGoATDiagrams()` (used in Hugo's tests for AsciiDoc GoAT diagram support) executing on a machine where `gem` is not on `$PATH` — e.g. asciidoctor installed via a system package without a full Ruby/RubyGems toolchain.

Common situations: Distro packages (`apt install asciidoctor`) that ship asciidoctor without exposing `gem`, minimal CI images, or Ruby installed via rbenv/asdf where shims aren't on PATH in the CI shell. Mostly encountered as a skipped-test reason in Hugo development.

Related errors

• the AsciiDoc converter (%s) is not installed
• the %s gem 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/14d0a1aed4fb5449.json. Report an issue: GitHub ↗.