{"id":"14d0a1aed4fb5449","repo":"gohugoio/hugo","slug":"the-rubygems-cli-s-is-not-installed","errorCode":null,"errorMessage":"the RubyGems CLI (%s) is not installed","messagePattern":"the RubyGems CLI \\((.+?)\\) is not installed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"markup/asciidocext/internal/converter.go","lineNumber":280,"sourceCode":"// 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.\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.","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/markup/asciidocext/internal/converter.go#L262-L298","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Install RubyGems (usually bundled with Ruby): `apt install ruby-full` or `brew install ruby`, then verify `gem --version`.","Add the Ruby bin directory to `$PATH` for the environment running the tests.","If you don't need GoAT diagram tests, ignore it — this check only gates that capability."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"gem\"); err != nil {\n    return fmt.Errorf(\"RubyGems CLI missing: %w\", err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install Ruby + RubyGems in build images that need AsciiDoc extensions","Run a preflight `gem --version` check in CI before the site build","Keep toolchain requirements in a setup script so all environments match"],"tags":["hugo","asciidoc","rubygems","dependency-check","tests"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}