oxc-project/oxc · warning

This module could be mistakenly parsed as script instead of

Error message

This module could be mistakenly parsed as script instead of module

What it means

This is oxlint's 'import/unambiguous' diagnostic. The rule runs only on files parsed as ES modules and reports those that contain no import or export statements at all. Such a file is syntactically valid as both a script and a module, so tools that must pick one (Node with/without "type": "module", bundlers, test runners) can guess wrong, changing semantics like strict mode and top-level this.

Source

Thrown at crates/oxc_linter/src/rules/import/unambiguous.rs:8

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

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

fn unambiguous_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("This module could be mistakenly parsed as script instead of module")
        .with_help("Add at least one import or export statement to unambiguously mark this file as a module")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct Unambiguous;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Warn if a `module` could be mistakenly parsed as a `script` instead of
    /// as a pure [ES module](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
    ///
    /// ### Why is this bad?
    ///
    /// For ESM-only environments, ambiguous files may lead to unexpected results and problems.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add an explicit empty export at the end of the file: export {};
2. If the file genuinely imports or should import something, add the real import/export statements.
3. If the file is meant to be a script, move it out of module contexts (rename to .cjs or remove "type": "module" handling) so the rule does not apply.
4. Disable the rule for script-like directories via overrides in .oxlintrc.json.

Example fix

// before (helpers.js in a "type": "module" package)
export {};
// (file originally had no import/export at all)

// after
export {}; // placed at the end of the file

// list module-context files lacking import/export (candidates for export {})
const { execSync } = require('node:child_process');
const files = execSync("rg -L --files-without-match '^(import|export)\\b' src/ --glob '*.mjs'", { encoding: 'utf8' });
console.log(files);

When it happens

Trigger: Enable import/unambiguous and lint a file that is treated as a module (e.g. .mjs, or a .js file in a "type": "module" package) but contains zero import/export declarations. The diagnostic fires with the help 'Add at least one import or export statement'.

Common situations: Published npm packages that ship plain helper files hit this because consumers may load the file as CommonJS. Monorepos where some packages set "type": "module" and others do not also produce ambiguous files. CI lint gates then fail on otherwise-working utility modules.

Related errors

• Expected {name} instead of {actual}
• Imported module should be assigned
• Prefer default export on a file with single export.
• Prefer default export to be present on every file that has e
• Type imports from declaration files must use top-level `impo

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