{"id":"8e6ede53fdb83973","repo":"gohugoio/hugo","slug":"failed-to-resolve-css-import-s-s","errorCode":null,"errorMessage":"failed to resolve CSS @import \"%s\"; %s","messagePattern":"failed to resolve CSS @import \"(.+?)\"; (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/resource_transformers/cssjs/inline_imports.go","lineNumber":122,"sourceCode":"\t\t\ttrackLine(i, offset, line)\n\t\t} else {\n\t\t\tpath := strings.Trim(strings.TrimPrefix(line, importIdentifier), \" \\\"';\")\n\t\t\tfilename := filepath.Join(basePath, path)\n\t\t\timp.dependencyManager.AddIdentity(identity.CleanStringIdentity(filename))\n\t\t\timportContent, hash := imp.contentHash(filename)\n\n\t\t\tif importContent == nil {\n\t\t\t\tif imp.opts.SkipInlineImportsNotFound {\n\t\t\t\t\ttrackLine(i, offset, line)\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\tpos := text.Position{\n\t\t\t\t\tFilename:     inPath,\n\t\t\t\t\tLineNumber:   offset + 1,\n\t\t\t\t\tColumnNumber: column + 1,\n\t\t\t\t}\n\t\t\t\tmsgDetail := \"if this import's source lives in node_modules, enable the skipInlineImportsNotFound option, see https://gohugo.io/functions/css/postcss/#skipinlineimportsnotfound\"\n\t\t\t\treturn 0, \"\", herrors.NewFileErrorFromFileInPos(fmt.Errorf(\"failed to resolve CSS @import \\\"%s\\\"; %s\", filename, msgDetail), pos, imp.fs, nil)\n\t\t\t}\n\n\t\t\ti--\n\n\t\t\tif imp.contentSeen[hash] {\n\t\t\t\ti++\n\t\t\t\t// Just replace the line with an empty string.\n\t\t\t\treplacements = append(replacements, []string{line, \"\"}...)\n\t\t\t\ttrackLine(i, offset, \"IMPORT\")\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\timp.contentSeen[hash] = true\n\n\t\t\t// Handle recursive imports.\n\t\t\tl, nested, err := imp.importRecursive(i+lineNum, string(importContent), filepath.ToSlash(filename))\n\t\t\tif err != nil {\n\t\t\t\treturn 0, \"\", err","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/resource_transformers/cssjs/inline_imports.go#L104-L140","documentation":"With `inlineImports = true`, Hugo's PostCSS/CSS transformer rewrites `@import` statements by inlining the imported file's content before invoking postcss. If the imported file can't be read from Hugo's asset filesystem, and `skipInlineImportsNotFound` is not enabled, the transform fails with a file-positioned error pointing at the offending @import line. Imports living in node_modules are the classic case, since they aren't in Hugo's assets mounts.","triggerScenarios":"`css.PostCSS (dict \"inlineImports\" true)` on a CSS file containing `@import \"foo.css\";` where foo.css does not exist relative to the importing file within Hugo's mounted assets; imports resolved by postcss-import from node_modules that Hugo's inliner can't see.","commonSituations":"Importing npm-package CSS (e.g. `@import \"normalize.css\";`) without mounting node_modules into assets; renamed or moved partial CSS files; path case mismatches on Linux CI vs macOS dev.","solutions":["If the import's source lives in node_modules, set `skipInlineImportsNotFound = true` in the PostCSS options so Hugo leaves it for postcss-import to resolve (see https://gohugo.io/functions/css/postcss/#skipinlineimportsnotfound).","Fix the @import path so it resolves relative to the importing file within assets.","Mount the needed directory (e.g. node_modules package) into assets via module mounts so Hugo can inline it."],"exampleFix":"// before (template)\n{{ $css := $styles | css.PostCSS (dict \"inlineImports\" true) }}\n// after\n{{ $css := $styles | css.PostCSS (dict \"inlineImports\" true \"skipInlineImportsNotFound\" true) }}","handlingStrategy":"validation","validationCode":"// before enabling inlineImports = true, verify every @import target exists in assets/\n// grep -o '@import \"[^\"]*\"' assets/css/main.css and check each file is mounted","typeGuard":null,"tryCatchPattern":"opts := map[string]any{\"inlineImports\": true, \"skipInlineImportsNotFound\": true} // only if missing imports are acceptable","preventionTips":["Keep all @import-ed CSS files under assets/ (or a mounted module dir) with paths relative to the importing file","Use `skipInlineImportsNotFound = true` deliberately for vendor URLs you can't inline, not as a blanket suppressor","Remember inlineImports only handles plain `@import \"...\";` — no media queries or url() forms"],"tags":["hugo","postcss","css","imports","assets"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}