What causes "the AsciiDoc converter (%s) is not installed" in gohugoio/hugo?

Install asciidoctor: `gem install asciidoctor` and confirm `which asciidoctor` succeeds.

the AsciiDoc converter (%s) is not installed

Error message

the AsciiDoc converter (%s) is not installed

What it means

Returned by `HasAsciiDoc()`, a capability probe that reports whether the `asciidoctor` binary is in `$PATH`. It is the same missing-binary condition as error 361 but surfaced from the availability check (used mainly by tests and feature detection) rather than mid-render.

Source

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

func (a *AsciiDocConverter) AppendArg(args []string, option, value, defaultValue string, allowedValues map[string]bool) []string {
	if value != defaultValue {
		if allowedValues[value] {
			args = append(args, option, value)
		} else {
			a.Cfg.Logger.Errorf(
				"Unsupported Asciidoctor value %q for option %q was passed in and will be ignored.",
				value,
				option,
			)
		}
	}
	return args
}

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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Install asciidoctor: `gem install asciidoctor` and confirm `which asciidoctor` succeeds.
Make sure the shell/CI environment running Hugo exports a `$PATH` that includes the Ruby gem bin directory.
If you only see this in test output, it's a skip condition — install the toolchain only if you need those tests to run.

Defensive patterns

Strategy: validation

Validate before calling

if _, err := exec.LookPath("asciidoctor"); err != nil {
    return fmt.Errorf("AsciiDoc converter missing: %w", err)
}

Prevention

Verify the configured AsciiDoc binary exists before invoking the build
Install asciidoctor via gem/package manager in every environment that renders .adoc
Fail fast in CI with an explicit preflight check rather than mid-build

When it happens

Trigger: Calling `internal.HasAsciiDoc()` (directly or via `CanRenderGoATDiagrams()` in Hugo's test suite) when `asciidoctor` is not resolvable in `$PATH`.

Common situations: Running Hugo's asciidocext tests locally or in CI without asciidoctor installed — the tests use this check to skip; developers see it when investigating skipped AsciiDoc/GoAT diagram tests or when tooling probes converter availability.

Related errors

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