{"record":{"id":"50841e8fec019b0f","repo":"gohugoio/hugo","slug":"error-copying-static-files-w","errorCode":null,"errorMessage":"error copying static files: %w","messagePattern":"error copying static files: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"commands/hugobuilder.go","lineNumber":577,"sourceCode":"func (c *hugoBuilder) fullBuild(noBuildLock bool) error {\n\tvar (\n\t\tg         errgroup.Group\n\t\tlangCount map[string]uint64\n\t)\n\n\tc.r.logger.Println(\"Start building sites … \")\n\tc.r.logger.Println(hugo.BuildVersionString())\n\tc.r.logger.Println()\n\tif terminal.IsTerminal(os.Stdout) {\n\t\tdefer func() {\n\t\t\tfmt.Print(showCursor + clearLine)\n\t\t}()\n\t}\n\n\tcopyStaticFunc := func() error {\n\t\tcnt, err := c.copyStatic()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error copying static files: %w\", err)\n\t\t}\n\t\tlangCount = cnt\n\t\treturn nil\n\t}\n\tbuildSitesFunc := func() error {\n\t\tif err := c.buildSites(noBuildLock); err != nil {\n\t\t\treturn fmt.Errorf(\"error building site: %w\", err)\n\t\t}\n\t\treturn nil\n\t}\n\t// Do not copy static files and build sites in parallel if cleanDestinationDir is enabled.\n\t// This flag deletes all static resources in /public folder that are missing in /static,\n\t// and it does so at the end of copyStatic() call.\n\tvar cleanDestinationDir bool\n\tc.withConf(func(conf *commonConfig) {\n\t\tcleanDestinationDir = conf.configs.Base.CleanDestinationDir\n\t})\n\tif cleanDestinationDir {","sourceCodeStart":559,"sourceCodeEnd":595,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/commands/hugobuilder.go#L559-L595","documentation":"During `fullBuild`, Hugo runs `c.copyStatic()` concurrently with site building. This error wraps any failure from copying the project's `static/` directory (and theme static dirs) into the publish directory. It surfaces I/O, symlink, or filesystem-layer problems rather than template/content problems.","triggerScenarios":"Fires when `copyStatic` returns non-nil — e.g. a static file is unreadable, a symlink loop exists, the destination is on a read-only filesystem, or a custom Hugo filesystem mount is misconfigured.","commonSituations":"A broken symlink or permission-restricted file under `static/`; a `publishDir` set to a read-only or out-of-space location; misconfigured module/theme static mounts pointing at non-existent paths; running out of inode/disk space during copy.","solutions":["Inspect the wrapped underlying error to locate the offending path.","Check permissions and resolve any broken symlinks under `static/` and theme static dirs.","Confirm the configured `publishDir` is writable and has free space.","Validate custom filesystem mounts in `hugo.toml` (the `[[mounts]]` blocks) point at real directories."],"exampleFix":"// before\n// static/img -> ../../missing   (broken symlink)\n// after\n// rm static/img && cp -r ../real/imgs static/img","handlingStrategy":"validation","validationCode":"// Pre-flight: walk the static dir and verify every file is readable;\n// check the publishDir is writable.\nfunc validateStatic(staticDir, publishDir string) error {\n  return filepath.Walk(staticDir, func(p string, fi os.FileInfo, err error) error {\n    if err != nil { return err }\n    if fi.IsDir() { return nil }\n    f, e := os.Open(p); if e != nil { return e }\n    return f.Close()\n  })\n}","typeGuard":"null","tryCatchPattern":"// On copyStatic failure, surface the offending path from the wrapped error.\nvar pathErr *os.PathError\nif errors.As(err, &pathErr) {\n  log.Printf(\"static copy failed at %s: %v\", pathErr.Path, pathErr)\n}","preventionTips":["Symlink-check `static/` and theme static dirs before building (`find -L static -type l`).","Confirm `publishDir` is on a writable volume with free space.","Verify `[[mounts]]` source paths in `hugo.toml` exist."],"tags":["hugo","static-files","filesystem","build"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}