{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/commands/hugobuilder.go#L559-L595","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped underlying error — it names the failing file or directory; fix that file/permission.","Ensure the publish directory (public/) is writable; delete it and rebuild if ownership is wrong.","Check static module mounts in the config for paths that don't exist.","Remove broken symlinks under static/."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// check static dirs exist and destination is writable before building\nfor _, d := range staticDirs {\n    if _, err := os.Stat(d); err != nil {\n        return fmt.Errorf(\"static dir missing: %w\", err)\n    }\n}","typeGuard":"var pathErr *os.PathError\nif errors.As(err, &pathErr) {\n    // filesystem failure during copy\n}","tryCatchPattern":"if err := b.build(); err != nil {\n    if strings.Contains(err.Error(), \"error copying static files\") {\n        // inspect wrapped cause: permissions, disk full, broken symlink\n        log.Printf(\"static copy failed: %v\", errors.Unwrap(err))\n    }\n    return err\n}","preventionTips":["Ensure the publish/destination directory is writable and has free disk space","Avoid broken symlinks and unreadable files inside static/","Don't run concurrent processes that delete or lock the output directory mid-build"],"tags":["hugo","static-files","build","filesystem"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}