gohugoio/hugo · error

invalid module.replacements: %q; configure replacement pairs

Error message

invalid module.replacements: %q; configure replacement pairs on the form "oldpath->newpath" 

What it means

Raised in decodeConfig (modules/config.go:212) while parsing module.replacements. Each entry must be a single 'oldpath->newpath' pair; strings.Split on '->' must yield exactly two parts. Any entry without exactly one arrow is rejected with the offending value quoted.

Source

Thrown at modules/config.go:212

		if err := mapstructure.WeakDecode(m, &c); err != nil {
			return c, err
		}

		if c.replacementsMap == nil {

			if len(c.Replacements) == 1 {
				c.Replacements = strings.Split(c.Replacements[0], ",")
			}

			for i, repl := range c.Replacements {
				c.Replacements[i] = strings.TrimSpace(repl)
			}

			c.replacementsMap = make(map[string]string)
			for _, repl := range c.Replacements {
				parts := strings.Split(repl, "->")
				if len(parts) != 2 {
					return c, fmt.Errorf(`invalid module.replacements: %q; configure replacement pairs on the form "oldpath->newpath" `, repl)
				}

				c.replacementsMap[strings.TrimSpace(parts[0])] = strings.TrimSpace(parts[1])
			}
		}

		if c.replacementsMap != nil && c.Imports != nil {
			for i, imp := range c.Imports {
				if newImp, found := c.replacementsMap[imp.Path]; found {
					imp.Path = newImp
					imp.pathProjectReplaced = true
					c.Imports[i] = imp
				}
			}
		}

		for i, mnt := range c.Mounts {
			mnt.Source = filepath.Clean(mnt.Source)

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Format every replacement as 'oldpath->newpath', e.g. 'github.com/a/b -> github.com/myfork/b'.
2. If using a single comma-separated string, ensure each comma-separated segment still contains exactly one '->'.
3. Remove empty or duplicate entries.

Example fix

// before
[module]
replacements = 'github.com/a/b'

// after
[module]
replacements = 'github.com/a/b -> github.com/myfork/b'

// validate replacements before feeding config to Hugo
for _, r := range cfg.Module.Replacements {
    parts := strings.Split(r, "->")
    if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || strings.TrimSpace(parts[1]) == "" {
        return fmt.Errorf("invalid replacement %q; use oldpath->newpath", r)
    }
}

When it happens

Trigger: module.replacements contains an entry lacking the '->' separator (e.g. 'github.com/a/b'), using the wrong arrow ('=>', '->'), or empty string. Also when a comma-separated single string has a malformed segment.

Common situations: Copying a replacement example and omitting the arrow; using 'new=old' YAML-style instead of the Hugo form; trailing commas producing an empty segment; whitespace-only entries.

Related errors

• cardinalityThreshold threshold must be between 0 and 100
• markup must not be set, use mediaType
• 'paginate' configuration setting must be positive to paginat
• permalink attribute not recognised
• invalid value for flag poll: %s

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/fe1520becd1873ad. Report an issue: GitHub.