Skip to content

BOM marker causes Next.js dev and build to fail #96374

Closed

Description

@terrymun

Link to the code that reproduces this issue

https://github.com/terrymun/Next.js-fails-with-BOM-marker-in-CSS

To Reproduce

  1. Check out the repo at . The trigger is to have one or more CSS files that contain the BOM marker, which is allowed based on CSS specifications.
  2. Build the Next.js app with pnpm build
  3. Notice you get the following error message:
> Build error occurred
Error: Turbopack build failed with 1 error:
./app/bom.css:1:2
Error: Parsing CSS source code failed
> 1 | @layer bom-layer {
    | ^
  2 |   .bom {
  3 |     color: blue;
  4 |   }

Unexpected token AtKeyword("layer")

Generated code of PostCSS transform of file content of app/bom.css:
./app/bom.css:1:2
> 1 | @layer bom-layer {
    | ^
  2 |   .bom {
  3 |     color: blue;
  4 |   }

Import trace:
  Client Component Browser:
    ./app/bom.css [Client Component Browser]
    ./app/layout.tsx [Server Component]


    at <unknown> (./app/bom.css:1:2)
    at <unknown> (./app/bom.css:1:2)

Current vs. Expected behavior

When a BOM marker is introduced into a CSS file, any attempts to serve or build the Next.js app will fail.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.5.0: Tue Jun  9 22:18:58 PDT 2026; root:xnu-12377.121.10~1/RELEASE_ARM64_T6000
  Available memory (MB): 32768
  Available CPU cores: 10
Binaries:
  Node: 26.3.1
  npm: 11.16.0
  Yarn: 1.22.19
  pnpm: 10.21.0
Relevant Packages:
  next: 16.3.0-canary.103 // Latest available version is detected (16.3.0-canary.103).
  eslint-config-next: N/A
  react: 19.2.8
  react-dom: 19.2.8
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

CSS

Which stage(s) are affected? (Select all that apply)

next build (local), next dev (local)

Additional context

Original context

The issue originally surfaced in a monorepo where I'm working on that uses Next.js 16.2.12 and it has postcss bumped to 8.5.24, which caused the build to start failing. Somewhere in the transformation a BOM character was introduced, which lightningcss will throw an error on.

I have initially reported this on postcss, and with the help of others it is discovered that postcss 8.5.24 helped to surface the issue: postcss/postcss#2122

Attempting to debug the issue specific to our repo with Claude Opus 5 yielded the following findings:

Step 1 — dart-sass emits a BOM in compressed mode

For non-ASCII output, dart-sass signals the encoding. In expanded mode it emits @charset "UTF-8"; in
compressed mode it emits a UTF-8 BOM instead, because a BOM is fewer bytes.

Our input is pure ASCII: content: ':\a0'. The escape \a0 decodes to a literal NBSP (C2 A0) in the
output, which is enough to trigger the BOM.

const sass = require('sass')
const src = '@layer a{.x::after{content:":\\a0"}}'

sass.compileString(src, { style: 'expanded' }).css
// '@charset "UTF-8";\n@layer a {\n  .x::after {\n    content: ": ";\n  }\n}'

sass.compileString(src, { style: 'compressed' }).css.charCodeAt(0) === 0xfeff
// true  <-- BOM, not @charset

This is long-standing, documented dart-sass behaviour and is suppressible with charset: false.

Step 2 — PostCSS 8.5.24 now re-emits that BOM

This is the only functional change between the two versions. lib/stringifier.js:

   root(node) {
+    if (node.source && node.source.input.hasBOM) {
+      this.builder('', node, 'start')
+    }
     this.body(node)

(The only other diff between 8.5.23 and 8.5.24 is the version string in lib/processor.js.)

PostCSS has always detected a BOM (Input#hasBOM, lib/input.js); 8.5.24 started round-tripping it on
stringify. 8.5.23 silently discarded it.

const plugin = { postcssPlugin: 'noop', Once() {} }
const css = sass.compileString(src, { style: 'compressed' }).css // has BOM

postcss([plugin]).process(css, { from: undefined }).css.charCodeAt(0) === 0xfeff
// 8.5.23 -> false   (BOM dropped)
// 8.5.24 -> true    (BOM preserved)

Note this requires at least one plugin with a visitor. With an empty plugin list PostCSS short-circuits and
returns the input string without stringifying, so the change is not observable — worth knowing when
reproducing.

Step 3 — Lightning CSS rejects the leading BOM

const lightningcss = require('lightningcss')

lightningcss.transform({ filename: 't.css', code: Buffer.from('@layer a{.x{color:red}}') })
// OK

lightningcss.transform({ filename: 't.css', code: Buffer.from('@layer a{.x{color:red}}') })
// ParserError: Unexpected token AtKeyword("layer")

The BOM is tokenized as content rather than skipped, so the parser is misaligned when it reaches @layer.

The error text visible in the Next.js output comes from Lightning CSS via Turbopack, not from PostCSS.
Symbols in next-swc.darwin-arm64.node locate it at turbopack_css::process
(turbopack/crates/turbopack-css/src/process.rs), and Unexpected token AtKeyword(...) is Lightning CSS's
ParserError::UnexpectedToken. A useful tell in the raw Next.js error is the column number — it reports
1:2 on the compressed line while @layer visibly begins at column 1, because the invisible BOM occupies
column 1.


Reproduction

I tried to reproduce this error with Next.js canary version, and it can be reliably reproduced without upgrading to postcss 8.5.23, as long as one or more CSS files contains a BOM marker, which is allowed baesd on CSS specification.

Activity

  1. added theissue type on Jul 30, 2026
  2. added a commit that references this issue on Aug 4, 2026
    ff3a2cf
  3. added a commit that references this issue on Aug 8, 2026
    888bda8
  4. github-actions commented on Sep 6, 2026

    @github-actions
    Contributor

    This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.

  5. locked as resolved and limited conversation to collaborators on Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions