What causes "failed to decode modules list: %w" in gohugoio/hugo?

Run `go list -m -json all` manually and check the output is pure JSON.

failed to decode modules list: %w

Error message

failed to decode modules list: %w

What it means

Returned when `go list -m -json` exited successfully but Hugo's streaming JSON decode of the concatenated module objects failed mid-stream. Indicates malformed or unexpected content in the list output rather than a listing failure.

Source

Thrown at modules/client.go:540

		args := []string{"list", "-m", "-json"}
		if len(modules) > 0 {
			args = append(args, modules...)
		} else {
			args = append(args, "all")
		}
		err := c.runGo(context.Background(), b, args...)
		if err != nil {
			return fmt.Errorf("failed to list modules: %w", err)
		}

		dec := json.NewDecoder(b)
		for {
			m := &goModule{}
			if err := dec.Decode(m); err != nil {
				if err == io.EOF {
					break
				}
				return fmt.Errorf("failed to decode modules list: %w", err)
			}

			if err := handle(m); err != nil {
				return err
			}
		}
		return nil
	}

	var modules goModules
	err := listAndDecodeModules(func(m *goModule) error {
		modules = append(modules, m)
		return nil
	})
	if err != nil {
		return nil, err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Run `go list -m -json all` manually and check the output is pure JSON.
Remove go wrappers/aliases that print extra text.
Upgrade Hugo to a version tested against your Go release.
Unset GODEBUG/GOFLAGS entries influencing go output.

Defensive patterns

Strategy: try-catch

Type guard

func isDecodeErr(err error) bool {
    var syntaxErr *json.SyntaxError
    return errors.As(err, &syntaxErr)
}

Try / catch

mods, err := client.List()
if err != nil {
    if isDecodeErr(err) {
        return fmt.Errorf("'go list -m -json' produced unparseable output; check Go toolchain version and that no wrapper pollutes stdout: %w", err)
    }
    return err
}

Prevention

Pin a supported Go toolchain version in CI images
Avoid shell wrappers/aliases around the go binary that print extra text to stdout
Treat decode errors as environment defects, not retryable conditions

When it happens

Trigger: json.Decoder hitting a non-EOF error while decoding the `go list -m -json` stream: extraneous stdout output from go wrappers, warnings interleaved into stdout, or output format changes across Go versions.

Common situations: go binary shims that echo to stdout, GODEBUG or toolchain-switch notices landing on stdout in unusual environments, very new Go releases altering field types.

Related errors

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