oxc-project/oxc · error · OxcDiagnostic

Expected Unicode BOM (Byte Order Mark)

Error message

Expected Unicode BOM (Byte Order Mark)

What it means

oxlint's `unicode-bom` rule (eslint plugin) requires or disallows a Unicode BOM (U+FEFF) at the start of every linted file. This variant is emitted from `run_once` when the rule option is "always" but `ctx.source_text()` does not start with U+FEFF (bytes EF BB BF). The diagnostic ships with an autofix that inserts the BOM at byte 0.

Source

Thrown at crates/oxc_linter/src/rules/eslint/unicode_bom.rs:19

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::{SPAN, Span};
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    context::LintContext,
    rule::{DefaultRuleConfig, Rule},
};

fn unexpected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Unexpected Unicode BOM (Byte Order Mark)")
        .with_help("File must not begin with the Unicode BOM")
        .with_label(span)
}

fn expected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Expected Unicode BOM (Byte Order Mark)")
        .with_help("File must begin with the Unicode BOM")
        .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct UnicodeBom(BomOptionType);

#[derive(Debug, Default, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
enum BomOptionType {
    /// Always require a Unicode BOM (Byte Order Mark) at the beginning of the file.
    Always,
    /// Never allow a Unicode BOM (Byte Order Mark) at the beginning of the file.
    /// This is the default option.
    #[default]
    Never,
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Save the file as UTF-8 with BOM (VS Code: click the encoding indicator, 'Save with Encoding', 'UTF-8 with BOM', or set "files.encoding": "utf8bom" for the file)
2. Run `oxlint --fix` on the file — the rule's fixer inserts the BOM automatically
3. If a BOM is not actually wanted, set the rule back to its default "never" or remove it from the config
4. Batch-convert with a script that prepends EF BB BF only to files confirmed to lack it

Example fix

// before — file starts with plain bytes, no BOM
const a = 1;

// after — file starts with U+FEFF (bytes EF BB BF), shown here as <BOM>
<BOM>const a = 1;

// .oxlintrc.json — make the policy explicit
{ "rules": { "unicode-bom": ["error", "always"] } }

# fast pre-check without running the full linter
for f in $(git ls-files '*.js' '*.ts'); do
  head -c 3 "$f" | od -An -tx1 | grep -q 'ef bb bf' || echo "missing BOM: $f"
done

When it happens

Trigger: Configuring `"unicode-bom": ["error", "always"]` in .oxlintrc.json (or an inherited ESLint config) and linting any file saved as plain UTF-8 without a BOM — the default for VS Code, WebStorm, and most POSIX editors.

Common situations: Teams inheriting legacy configs from Windows/Visual Studio shops where "always" was the norm; editors silently stripping the BOM on save (VS Code default files.encoding utf8); files converted between encodings; mixed-encoding monorepos where only some files carry a BOM.

Related errors

• Unexpected Unicode BOM (Byte Order Mark)
• Use the 'v' flag.
• Use the 'u' flag.
• Empty array binding pattern
• Empty object binding pattern

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/5e0095f5903e962a. Report an issue: GitHub.