{"record":{"id":"7c409245410d98c6","repo":"oxc-project/oxc","slug":"unexpected-unicode-bom-byte-order-mark","errorCode":null,"errorMessage":"Unexpected Unicode BOM (Byte Order Mark)","messagePattern":"Unexpected Unicode BOM \\(Byte Order Mark\\)","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/eslint/unicode_bom.rs","lineNumber":13,"sourceCode":"use oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::{SPAN, Span};\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    context::LintContext,\n    rule::{DefaultRuleConfig, Rule},\n};\n\nfn unexpected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Unexpected Unicode BOM (Byte Order Mark)\")\n        .with_help(\"File must not begin with the Unicode BOM\")\n        .with_label(span)\n}\n\nfn expected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Expected Unicode BOM (Byte Order Mark)\")\n        .with_help(\"File must begin with the Unicode BOM\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone, Deserialize)]\npub struct UnicodeBom(BomOptionType);\n\n#[derive(Debug, Default, Clone, Deserialize, JsonSchema)]\n#[serde(rename_all = \"kebab-case\")]\nenum BomOptionType {\n    /// Always require a Unicode BOM (Byte Order Mark) at the beginning of the file.\n    Always,","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/eslint/unicode_bom.rs#L1-L31","documentation":"oxlint `eslint/unicode-bom` with the default `\"never\"` option: the source file begins with a UTF-8 BOM (U+FEFF, bytes EF BB BF). `unexpected_unicode_bom_diagnostic` (unicode_bom.rs:13) reports it; the run_once check (unicode_bom.rs:71-79) tests `source.starts_with('\\u{feff}')` and offers a fix that deletes the first 3 bytes. UTF-8 does not need a BOM since byte order is irrelevant, so 'never' is the default per the rule docs.","triggerScenarios":"Any file whose first character is U+FEFF while the rule is configured `\"never\"` (or unconfigured, since Never is the default BomOptionType). Editors or PowerShell `Out-File` commonly prepend the BOM.","commonSituations":"Files saved on Windows with a BOM-producing editor; files piped through PowerShell redirects; concatenating files where a mid-stream BOM landed at the start; a CI lint step suddenly failing after a Windows contributor's commit.","solutions":["Re-save the file as UTF-8 without BOM (`:set nobomb` in vim; 'Save with encoding → UTF-8' in VS Code; `dos2unix` also strips it).","Run `oxlint --fix` — the rule's fixer deletes the 3 BOM bytes (Span 0..3).","Strip via CLI: `sed -i '1s/^\\xEF\\xBB\\xBF//' file.js`.","If your toolchain genuinely requires a BOM, configure `\"unicode-bom\": \"always\"` instead."],"exampleFix":"// before (file bytes: EF BB BF)\n\\uFEFFexport const a = 1;\n\n// after (plain UTF-8, no leading U+FEFF)\nexport const a = 1;","handlingStrategy":"validation","validationCode":"# fail if any source file starts with a UTF-8 BOM (EF BB BF)\nfor f in $(git ls-files '*.js' '*.ts' '*.mjs' '*.cjs'); do\n  head -c3 \"$f\" | od -An -tx1 | grep -q 'ef bb bf' && echo \"BOM: $f\"\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Configure your editor to save 'UTF-8 (no BOM)' and add a `.editorconfig` with `charset = utf-8`.","Avoid PowerShell `Out-File`/`>` redirects for source files; they prepend a BOM by default in Windows PowerShell.","Run `oxlint --fix` after Windows contributors' commits — the unicode-bom fixer strips the 3 bytes safely."],"tags":["eslint","oxlint","unicode","bom","encoding","lint"],"backgroundTag":"unicode-bom-in-source","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}