gohugoio/hugo · error

error copying static files: %w

Error message

error copying static files: %w

What it means

Wrapper added in fullBuild around copyStatic, which syncs files from the static directories (and mounted static content) into the publish directory. Any failure while enumerating or copying static files is wrapped with this message so the user knows the build failed in the static-sync phase rather than site rendering.

Source

Thrown at commands/hugobuilder.go:577

func (c *hugoBuilder) fullBuild(noBuildLock bool) error {
	var (
		g         errgroup.Group
		langCount map[string]uint64
	)

	c.r.logger.Println("Start building sites … ")
	c.r.logger.Println(hugo.BuildVersionString())
	c.r.logger.Println()
	if terminal.IsTerminal(os.Stdout) {
		defer func() {
			fmt.Print(showCursor + clearLine)
		}()
	}

	copyStaticFunc := func() error {
		cnt, err := c.copyStatic()
		if err != nil {
			return fmt.Errorf("error copying static files: %w", err)
		}
		langCount = cnt
		return nil
	}
	buildSitesFunc := func() error {
		if err := c.buildSites(noBuildLock); err != nil {
			return fmt.Errorf("error building site: %w", err)
		}
		return nil
	}
	// Do not copy static files and build sites in parallel if cleanDestinationDir is enabled.
	// This flag deletes all static resources in /public folder that are missing in /static,
	// and it does so at the end of copyStatic() call.
	var cleanDestinationDir bool
	c.withConf(func(conf *commonConfig) {
		cleanDestinationDir = conf.configs.Base.CleanDestinationDir
	})
	if cleanDestinationDir {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped underlying error — it names the failing file or directory; fix that file/permission.
2. Ensure the publish directory (public/) is writable; delete it and rebuild if ownership is wrong.
3. Check static module mounts in the config for paths that don't exist.
4. Remove broken symlinks under static/.

// check static dirs exist and destination is writable before building
for _, d := range staticDirs {
    if _, err := os.Stat(d); err != nil {
        return fmt.Errorf("static dir missing: %w", err)
    }
}

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    // filesystem failure during copy
}

if err := b.build(); err != nil {
    if strings.Contains(err.Error(), "error copying static files") {
        // inspect wrapped cause: permissions, disk full, broken symlink
        log.Printf("static copy failed: %v", errors.Unwrap(err))
    }
    return err
}

When it happens

Trigger: copyStatic returning an error during `hugo` or `hugo server` full builds: unreadable files under static/, permission errors writing to publishDir, broken symlinks, invalid static mounts in module config, or disk-full conditions.

Common situations: Permission problems on the public/ output directory (e.g. previously created by root or another container user), broken symlinks in static/, misconfigured [[module.mounts]] entries for static, or cleanDestinationDir interacting with files it cannot delete.

Related errors

• failed to acquire a build lock: %w
• failed to save file %q:: %w
• failed to resolve output path %q: %w
• failed to copy %q to %q: %w
• target path "%s" exists but is not a directory

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