gohugoio/hugo · error

failed to open non-content file: %w

Error message

failed to open non-content file: %w

What it means

When `hugo new` runs with a directory archetype (bundle archetype), files inside it are split into content files (executed as templates) and 'other' files copied verbatim. This error occurs while copying an 'other' (non-content) file: opening the source file from the archetype filesystem via meta.Open() failed, wrapping the underlying OS error.

Source

Thrown at create/content.go:190

	}

	if err := b.h.Build(hugolib.BuildCfg{NoBuildLock: true, SkipRender: true, ContentInclusionFilter: contentInclusionFilter}); err != nil {
		return err
	}

	for i, filename := range contentTargetFilenames {
		if err := b.applyArcheType(filename, b.dirMap.contentFiles[i]); err != nil {
			return err
		}
	}

	// Copy the rest as is.
	for _, fi := range b.dirMap.otherFiles {
		meta := fi.Meta()

		in, err := meta.Open()
		if err != nil {
			return fmt.Errorf("failed to open non-content file: %w", err)
		}
		targetFilename := filepath.Join(baseDir, b.targetPath, strings.TrimPrefix(fi.Meta().Filename, b.archetypeFi.Meta().Filename))
		targetDir := filepath.Dir(targetFilename)

		if err := b.sourceFs.MkdirAll(targetDir, 0o777); err != nil && !os.IsExist(err) {
			return fmt.Errorf("failed to create target directory for %q: %w", targetDir, err)
		}

		out, err := b.sourceFs.Create(targetFilename)
		if err != nil {
			return err
		}

		_, err = io.Copy(out, in)
		if err != nil {
			return err
		}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check the wrapped error for the OS cause and fix permissions on the file inside archetypes/ (chmod it readable).
2. Remove or fix broken symlinks in the archetype directory.
3. If the archetype comes from a module/theme, run `hugo mod verify`/re-vendor to restore intact files.

if fi, err := os.Stat(src); err != nil || !fi.Mode().IsRegular() {
    return fmt.Errorf("archetype asset %q unreadable", src)
}

func isNotExist(err error) bool { return errors.Is(err, fs.ErrNotExist) }

if err := create.NewContent(...); err != nil {
    if errors.Is(err, fs.ErrNotExist) || errors.Is(err, fs.ErrPermission) {
        // fix archetype bundle file permissions/paths
    }
    return err
}

When it happens

Trigger: contentBuilder.buildDir copying b.dirMap.otherFiles — e.g. an image or data file inside archetypes/<kind>/ — when Open() on that archetype file returns an error (permission denied, file deleted between walk and copy, broken symlink, I/O error).

Common situations: Unreadable file permissions inside the archetype directory; dangling symlinks in a theme's or module's archetype bundle; archetype files modified/removed concurrently; module-mounted archetype filesystems with access problems.

Related errors

• failed to create target directory for %q: %w
• failed to walk archetype dir %q: %w
• failed to save file %q:: %w
• failed to save file %q: %s
• failed to create workingDir: %w

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