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.parseFileSync() is synchronous and reads the file from disk inside the native binding. When the native binding did not load but the @swc/wasm fallback is present, it throws 'Fallback bindings does not support filesystem access' (note: this message variant has no trailing period) because the fallback intentionally does no filesystem I/O. Your process is running on @swc/wasm and called a native-only, file-based API.

Source

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

            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" };
        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.");
        }

        return parseProgramJson(bindings.parseFileSync(path, toBuffer(options)));
    }

    /**
     * Note: this method should be invoked on the compiler instance used
     *  for `parse()` / `parseSync()`.
     */
    async print(m: Program, options?: Options): Promise<Output> {
        options = options || {};

        if (bindings) {
            return bindings.print(stringifyProgram(m), toBuffer(options));

View on GitHub (pinned to 5176682b65)

Solutions

Repair the native install (clean reinstall with optional platform packages) — the sync file API only exists natively
If staying on the fallback, read the file yourself and call the content-based API: `compiler.parseSync(fs.readFileSync(path, 'utf8'), opts)` (parse itself still needs native bindings for AST output)
Validate or unset SWC_BINARY_PATH
Pin the platform package as an explicit optionalDependency so it isn't skipped

Example fix

// before
const ast = compiler.parseFileSync(path);

// after: read in JS, parse the contents (native bindings still required for parse)
const ast = compiler.parseSync(require('fs').readFileSync(path, 'utf8'));

Defensive patterns

Strategy: validation

Validate before calling

const { Compiler } = require('@swc/core');
function canUseFileSyncApis() {
  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;
    }
    throw e;
  }
}

Try / catch

try {
  const ast = compiler.parseFileSync(path, opts);
} catch (e) {
  if (e instanceof Error && /Fallback bindings does not support filesystem access/.test(e.message)) {
    // WASM fallback active: read the file yourself, then call the content-based API
    const src = require('fs').readFileSync(path, 'utf8');
  }
  throw e;
}

Prevention

Check for native bindings before sync file-based SWC calls; they only exist in native mode
Use content-based APIs in environments that may run the WASM fallback
Fix installs so native bindings load instead of permanently working around the fallback

When it happens

Trigger: `compiler.parseFileSync(path, opts)` when require('./binding.js') failed and @swc/wasm was loaded — missing platform package, invalid SWC_BINARY_PATH, or a runtime where native addons can't load.

Common situations: Synchronous codemod/CLI paths in containers with pruned optional packages; sandboxed runtimes rejecting native modules; postinstall failures silently switching the engine to WASM.

Related errors

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