{"id":"8d93869404c620f2","repo":"gohugoio/hugo","slug":"the-s-gem-is-not-installed","errorCode":null,"errorMessage":"the %s gem is not installed","messagePattern":"the (.+?) gem is not installed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"markup/asciidocext/internal/converter.go","lineNumber":295,"sourceCode":"\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.\n\tsc := security.DefaultConfig\n\tsc.Exec.Allow = security.MustNewWhitelist(gemBinaryName)\n\tex := hexec.New(sc, \"\", loggers.NewDefault())\n\n\targs := []any{\"list\", asciiDocDiagramExtension, \"--installed\"}\n\tcmd, err := ex.New(gemBinaryName, args...)\n\tif err != nil {\n\t\treturn false, err\n\t}\n\terr = cmd.Run()\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"the %s gem is not installed\", asciiDocDiagramExtension)\n\t}\n\n\t// Verify that the GoAT CLI is installed.\n\tif !hexec.InPath(goatBinaryName) {\n\t\treturn false, fmt.Errorf(\"the GoAT CLI (%s) is not installed\", goatBinaryName)\n\t}\n\n\treturn true, nil\n}\n\n// extractTOC extracts the toc from the given src html.\n// It returns the html without the TOC, and the TOC data\nfunc (a *AsciiDocConverter) extractTOC(src []byte) ([]byte, *tableofcontents.Fragments, error) {\n\tvar buf bytes.Buffer\n\tbuf.Write(src)\n\tnode, err := html.Parse(&buf)\n\tif err != nil {\n\t\treturn nil, nil, err","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/markup/asciidocext/internal/converter.go#L277-L313","documentation":"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`).","triggerScenarios":"`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).","commonSituations":"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.","solutions":["Install the gem: `gem install asciidoctor-diagram`, then verify with `gem list asciidoctor-diagram --installed`.","If using rbenv/rvm/asdf, ensure the active Ruby matches the one whose `gem` is on PATH (`gem env` vs `which asciidoctor`).","In CI, add the gem install step to the image or pipeline before the Hugo build/tests."],"exampleFix":"# before\ngem install asciidoctor\n# after\ngem install asciidoctor asciidoctor-diagram","handlingStrategy":"validation","validationCode":"out, err := exec.Command(\"gem\", \"list\", \"--local\", \"asciidoctor-diagram\").Output()\nif err != nil || !strings.Contains(string(out), \"asciidoctor-diagram\") {\n    return errors.New(\"required gem not installed\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Preinstall required gems (e.g. asciidoctor-diagram) via a Gemfile or setup script","Verify with `gem list` in CI before building","Only enable AsciiDoc extensions in config that are actually installed"],"tags":["hugo","asciidoc","asciidoctor-diagram","rubygems","dependency-check"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}