oxc-project/oxc · error · OxcDiagnostic

Arbitrary module namespace identifier names are not availabl

Error message

Arbitrary module namespace identifier names are not available in the configured target environment.

What it means

Warning raised by the oxc transformer's ES2020 pass (crates/oxc_transformer/src/es2020/mod.rs, `enter_import_specifier`). When `arbitrary_module_namespace_names` is enabled (compile target predates the ES2022 feature) and an ImportSpecifier's `imported` name is a StringLiteral, the pass records this diagnostic. `import { "odd name" as x } from 'm'` is the ES2022 'arbitrary module namespace names' feature; oxc has no downlevel transform for it, so the string-named import is reported and passes through unchanged.

Source

Thrown at crates/oxc_transformer/src/es2020/mod.rs:91

    fn enter_big_int_literal(&mut self, node: &mut BigIntLiteral<'a>, ctx: &mut TraverseCtx<'a>) {
        if self.options.big_int {
            let warning = OxcDiagnostic::warn(
                "Big integer literals are not available in the configured target environment.",
            )
            .with_label(node.span);
            ctx.state.error(warning);
        }
    }

    fn enter_import_specifier(
        &mut self,
        node: &mut ImportSpecifier<'a>,
        ctx: &mut TraverseCtx<'a>,
    ) {
        if self.options.arbitrary_module_namespace_names
            && let ModuleExportName::StringLiteral(literal) = &node.imported
        {
            let warning = OxcDiagnostic::warn(
                "Arbitrary module namespace identifier names are not available in the configured target environment.",
            )
            .with_label(literal.span);
            ctx.state.error(warning);
        }
    }

    fn enter_export_specifier(
        &mut self,
        node: &mut ExportSpecifier<'a>,
        ctx: &mut TraverseCtx<'a>,
    ) {
        if self.options.arbitrary_module_namespace_names {
            if let ModuleExportName::StringLiteral(literal) = &node.exported {
                let warning = OxcDiagnostic::warn(
                    "Arbitrary module namespace identifier names are not available in the configured target environment.",
                )
                .with_label(literal.span);

View on GitHub (pinned to e1e7af627c)

Solutions

Raise the target to ES2022+ so arbitrary module namespace names are supported natively.
Rewrite the import to a plain identifier if the module also exports an identifier binding, or re-export the string-named export under an identifier name in a small helper module.
Use a namespace import instead: `import * as m from './mod'` and access `m['odd name']`.
Remove the import if it is unused.

Example fix

// before
import { "odd-name" as oddName } from './mod';

// after
import * as m from './mod';
const oddName = m['odd-name'];

Defensive patterns

Strategy: validation

Validate before calling

// Detect string-named imports (ES2022 arbitrary module namespace names)
if (/import\s*\{\s*["'][^"']+["']\s+as\s+/.test(source)) {
  throw new Error('String-named import requires an ES2022+ target or must be rewritten');
}

Try / catch

const result = transform('foo.ts', source, options);
const nsErrors = result.errors.filter(e => e.message.includes('Arbitrary module namespace'));
if (nsErrors.length) { /* raise target or rewrite the imports, then fail the build */ }

Prevention

Prefer identifier imports; keep string names only at interop boundaries with a modern target.
Set target once from browserslist and verify it is ES2022+ before adopting string-named imports.
Fail builds on any transformer diagnostic rather than shipping untransformed syntax.

When it happens

Trigger: Transforming `import { "string name" as local } from './mod'` (note the quoted string in the import position) with a target below ES2022 / options.arbitrary_module_namespace_names = true. One diagnostic per offending specifier, labeled with the string literal's span.

Common situations: Consuming generated or interop-oriented packages that export non-identifier names (e.g. `import { "jest-mock" as mock }`); transpiling with legacy browserslist targets; bundler output that preserved string import names from a source file.

Related errors

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