gohugoio/hugo · error

failed to init mount

Error message

failed to init mount %d: %w

What it means

In decodeConfig (modules/config.go:233) every user-declared [[module.mounts]] entry has its source/target cleaned and then mnt.init(logger) called. Failure wraps the zero-based mount index. This is the user-config counterpart of error 485.

Solutions

1. Inspect the mount at the reported index and fix its sites.matrix / remove legacy lang key.
2. Update the theme/module to a version compatible with your Hugo release.
3. Validate the full [[module.mounts]] block for consistent keys.

Example fix

// before (mount at reported index)
[[module.mounts]]
source = "assets"
target = "assets"
lang = "en"

// after
[[module.mounts]]
source = "assets"
target = "assets"

for i := range cfg.Module.Mounts {
    m := &cfg.Module.Mounts[i]
    if m.Source == "" || m.Target == "" {
        return fmt.Errorf("mount #%d: source and target required", i)
    }
    if m.Lang != "" && len(m.Sites.Matrix.Languages) > 0 {
        return fmt.Errorf("mount #%d: choose either lang or sites.matrix", i)
    }
}

When it happens

Trigger: A [[module.mounts]] entry in your config (or a theme/module config) provides an invalid sites.matrix / lang combination that Mount.init rejects during normalization.

Common situations: Hand-editing mounts and introducing a malformed sites.matrix; mixing the deprecated 'lang' key with sites.matrix on the same mount; themes shipping outdated mount configs after a Hugo upgrade.

Related errors

• : mount target must be one of
• cannot use --renderToMemory with --destination
• cardinalityThreshold threshold must be between 0 and 100
• failed to compile permalink target
• failed to create baseURL from

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

Appendix: source

Thrown at modules/config.go:233

				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)
			mnt.Target = filepath.Clean(mnt.Target)
			if err := mnt.init(logger); err != nil {
				return c, fmt.Errorf("failed to init mount %d: %w", i, err)
			}
			c.Mounts[i] = mnt
		}

		if c.Workspace == "" {
			c.Workspace = WorkspaceDisabled
		}
		if c.Workspace != WorkspaceDisabled {
			c.Workspace = filepath.Clean(c.Workspace)
			if !filepath.IsAbs(c.Workspace) {
				workingDir := cfg.GetString("workingDir")
				c.Workspace = filepath.Join(workingDir, c.Workspace)
			}
			if _, err := os.Stat(c.Workspace); err != nil {
				//lint:ignore ST1005 end user message.
				return c, fmt.Errorf("module workspace %q does not exist. Check your module.workspace setting (or HUGO_MODULE_WORKSPACE env var).", c.Workspace)
			}
		}

View on GitHub (pinned to 52c9bd7908)