{"id":"a3e61b6c5c1053af","repo":"gohugoio/hugo","slug":"failed-to-open-translations-file-q-w","errorCode":null,"errorMessage":"failed to open translations file %q:: %w","messagePattern":"failed to open translations file %q:: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"langs/i18n/translationProvider.go","lineNumber":110,"sourceCode":"\tfor _, info := range files {\n\t\tif err := addTranslationFile(bundle, source.NewFileInfo(info)); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\ttp.t = NewTranslator(bundle, dst.Conf, dst.Log)\n\n\tdst.Translate = tp.getTranslateFunc(dst)\n\n\treturn nil\n}\n\nconst artificialLangTagPrefix = \"art-x-\"\n\nfunc addTranslationFile(bundle *i18n.Bundle, r *source.File) error {\n\tf, err := r.FileInfo().Meta().Open()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to open translations file %q:: %w\", r.LogicalName(), err)\n\t}\n\n\tb := helpers.ReaderToBytes(f)\n\tf.Close()\n\n\tname := r.LogicalName()\n\tlang := paths.Filename(name)\n\ttag := language.Make(lang)\n\tif tag == language.Und {\n\t\ttry := artificialLangTagPrefix + lang\n\t\t_, err = language.Parse(try)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"%q: %s\", try, err)\n\t\t}\n\t\tname = artificialLangTagPrefix + name\n\t}\n\n\t_, err = bundle.ParseMessageFileBytes(b, name)","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/langs/i18n/translationProvider.go#L92-L128","documentation":"Raised in addTranslationFile (langs/i18n/translationProvider.go:110) when opening an i18n translation file from the mounted filesystem fails before parsing. Hugo walks all files in the i18n component (project, themes, modules) and opens each to feed go-i18n's bundle; an Open error here is an I/O problem — the file exists in the directory listing but can't be read. (The doubled \"::\" in the message is a long-standing quirk of the format string.)","triggerScenarios":"An i18n/*.{yaml,toml,json} file that is unreadable at open time: permission denied, a broken symlink inside i18n/, a file removed between walk and open, or a module mount pointing at a path that fails on read.","commonSituations":"Broken symlinks in themes or vendored modules, restrictive file permissions after copying files as root (e.g. in Docker builds), or network/overlay filesystems dropping files mid-build.","solutions":["Check the named file exists and is readable: `ls -l i18n/` in the project and in any theme/module providing it.","Fix broken symlinks or restore the missing target file.","Correct permissions (e.g. `chmod a+r i18n/*.yaml`), especially in container builds.","If the file comes from a module, re-vendor or re-fetch (`hugo mod vendor` / `hugo mod get -u`)."],"exampleFix":"# before: i18n/en.yaml is a broken symlink\n$ ls -l i18n/en.yaml\nlrwxrwxrwx en.yaml -> ../shared/en.yaml (missing)\n# after: replace with the real file\n$ cp ../shared-i18n/en.yaml i18n/en.yaml","handlingStrategy":"validation","validationCode":"// Verify i18n files exist and are readable before build\nentries, err := os.ReadDir(\"i18n\")\nif err == nil {\n    for _, e := range entries {\n        f, err := os.Open(filepath.Join(\"i18n\", e.Name()))\n        if err != nil { return fmt.Errorf(\"unreadable translation file %s: %w\", e.Name(), err) }\n        f.Close()\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to open translations file\") {\n    return fmt.Errorf(\"check the named i18n file exists, is readable, and isn't a broken symlink: %w\", err)\n}","preventionTips":["Keep i18n files named by language code with a supported extension (en.toml, fr.yaml, de.json)","Check file permissions on i18n/ files, especially after CI checkouts or Docker COPY","Avoid broken symlinks in i18n directories (symlinks may also be restricted by Hugo's security model)","Validate i18n files parse by running a local `hugo` build before pushing"],"tags":["hugo","i18n","filesystem","translations"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}