{"id":"d2986acf3236f6a3","repo":"gohugoio/hugo","slug":"the-asciidoc-converter-s-is-not-installed","errorCode":null,"errorMessage":"the AsciiDoc converter (%s) is not installed","messagePattern":"the AsciiDoc converter \\((.+?)\\) is not installed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"markup/asciidocext/internal/converter.go","lineNumber":265,"sourceCode":"func (a *AsciiDocConverter) AppendArg(args []string, option, value, defaultValue string, allowedValues map[string]bool) []string {\n\tif value != defaultValue {\n\t\tif allowedValues[value] {\n\t\t\targs = append(args, option, value)\n\t\t} else {\n\t\t\ta.Cfg.Logger.Errorf(\n\t\t\t\t\"Unsupported Asciidoctor value %q for option %q was passed in and will be ignored.\",\n\t\t\t\tvalue,\n\t\t\t\toption,\n\t\t\t)\n\t\t}\n\t}\n\treturn args\n}\n\n// HasAsciiDoc reports whether the AsciiDoc converter is installed.\nfunc HasAsciiDoc() (bool, error) {\n\tif !hexec.InPath(asciiDocBinaryName) {\n\t\treturn false, fmt.Errorf(\"the AsciiDoc converter (%s) is not installed\", asciiDocBinaryName)\n\t}\n\treturn true, nil\n}\n\n// CanRenderGoATDiagrams reports whether the AsciiDoc converter can render\n// GoAT diagrams. Only used in tests.\nfunc CanRenderGoATDiagrams() (bool, error) {\n\t// Verify that the AsciiDoc converter is installed.\n\tif ok, err := HasAsciiDoc(); !ok {\n\t\treturn false, err\n\t}\n\n\t// Verify that the RubyGems CLI is installed.\n\tif !hexec.InPath(gemBinaryName) {\n\t\treturn false, fmt.Errorf(\"the RubyGems CLI (%s) is not installed\", gemBinaryName)\n\t}\n\n\t// Verify that the required AsciiDoc converter extension is installed.","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/markup/asciidocext/internal/converter.go#L247-L283","documentation":"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.","triggerScenarios":"Calling `internal.HasAsciiDoc()` (directly or via `CanRenderGoATDiagrams()` in Hugo's test suite) when `asciidoctor` is not resolvable in `$PATH`.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"asciidoctor\"); err != nil {\n    return fmt.Errorf(\"AsciiDoc converter missing: %w\", err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["hugo","asciidoc","asciidoctor","dependency-check","tests"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}