swc-project/swc · error · Error

Fallback bindings does not support filesystem access.

Error message

Fallback bindings does not support filesystem access.

What it means

Compiler.parseFile() reads and parses a file inside the native binding, which has filesystem access. When the native binding did not load but the @swc/wasm fallback is present, the method throws 'Fallback bindings does not support filesystem access.' rather than degrading: the WASM fallback deliberately performs no disk I/O. Seeing this means your process is on the fallback and you used a file-based, native-only API.

Source

Thrown at packages/core/src/index.ts:231

            );
        } else if (fallbackBindings) {
            return fallbackBindings.parseSync(src, options);
        }

        throw new Error("Bindings not found.");
    }

    parseFile(
        path: string,
        options: ParseOptions & { isModule: false }
    ): Promise<Script>;
    parseFile(path: string, options?: ParseOptions): Promise<Module>;
    async parseFile(path: string, options?: ParseOptions): Promise<Program> {
        options = options || { syntax: "ecmascript" };
        options.syntax = options.syntax || "ecmascript";

        if (!bindings && !!fallbackBindings) {
            throw new Error(
                "Fallback bindings does not support filesystem access."
            );
        } else if (!bindings) {
            throw new Error("Bindings not found.");
        }

        const res = await bindings.parseFile(path, toBuffer(options));

        return parseProgramJson(res);
    }

    parseFileSync(
        path: string,
        options: ParseOptions & { isModule: false }
    ): Script;
    parseFileSync(path: string, options?: ParseOptions): Module;
    parseFileSync(path: string, options?: ParseOptions): Program {
        options = options || { syntax: "ecmascript" };

View on GitHub (pinned to 5176682b65)

Solutions

Repair the native install so the file-based API works: clean reinstall with optional platform packages (`rm -rf node_modules package-lock.json && npm install --include=optional`)
If you must stay on the fallback, read the file in JS and use the content-based API: `compiler.parse(await fs.readFile(path, 'utf8'), opts)` — note parse itself is also native-only, so native bindings are ultimately required for AST output
Validate or unset SWC_BINARY_PATH if it broke native loading
Pin the matching platform package as an explicit optionalDependency

Example fix

// before
const ast = await compiler.parseFile(path, { syntax: 'typescript' });

// after: read in JS, parse the contents (native bindings still required for parse)
const { readFile } = require('fs/promises');
const ast = await compiler.parse(await readFile(path, 'utf8'), { syntax: 'typescript' });

Defensive patterns

Strategy: validation

Validate before calling

const { Compiler } = require('@swc/core');
async function canUseFileApis() {
  try {
    new Compiler().parseSync(''); // native-only probe
    return true;
  } catch (e) {
    if (e instanceof Error && /does not support this interface|Bindings not found|filesystem access/.test(e.message)) {
      return false; // WASM fallback or broken install — avoid file-based APIs
    }
    throw e;
  }
}

Try / catch

try {
  const ast = await compiler.parseFile(path, opts);
} catch (e) {
  if (e instanceof Error && /Fallback bindings does not support filesystem access/.test(e.message)) {
    // on the WASM fallback: read the file in JS and use content-based APIs
    const src = await require('fs/promises').readFile(path, 'utf8');
  }
  throw e;
}

Prevention

Detect native-vs-fallback mode at boot and gate all file-based SWC APIs behind it
Prefer content-based APIs (parse/transform on strings) in portable code; do file reads yourself
Repair native installs (optionals enabled) before relying on parseFile in CLIs and codemods

When it happens

Trigger: `await compiler.parseFile(path, opts)` when require('./binding.js') failed and @swc/wasm was loaded — broken/missing platform package, invalid SWC_BINARY_PATH, or environments (browser, sandboxed runtimes) where native addons can't load.

Common situations: Codemods/CLIs run in containers whose install pruned optional packages; serverless environments without native addon support; CI where a broken postinstall left @swc/wasm as the active engine.

Related errors

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/cc7cd92aaac77021. Report an issue: GitHub.