{"record":{"id":"cc7cd92aaac77021","repo":"swc-project/swc","slug":"fallback-bindings-does-not-support-filesystem-acce","errorCode":null,"errorMessage":"Fallback bindings does not support filesystem access.","messagePattern":"Fallback bindings does not support filesystem access\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/index.ts","lineNumber":231,"sourceCode":"            );\n        } else if (fallbackBindings) {\n            return fallbackBindings.parseSync(src, options);\n        }\n\n        throw new Error(\"Bindings not found.\");\n    }\n\n    parseFile(\n        path: string,\n        options: ParseOptions & { isModule: false }\n    ): Promise<Script>;\n    parseFile(path: string, options?: ParseOptions): Promise<Module>;\n    async parseFile(path: string, options?: ParseOptions): Promise<Program> {\n        options = options || { syntax: \"ecmascript\" };\n        options.syntax = options.syntax || \"ecmascript\";\n\n        if (!bindings && !!fallbackBindings) {\n            throw new Error(\n                \"Fallback bindings does not support filesystem access.\"\n            );\n        } else if (!bindings) {\n            throw new Error(\"Bindings not found.\");\n        }\n\n        const res = await bindings.parseFile(path, toBuffer(options));\n\n        return parseProgramJson(res);\n    }\n\n    parseFileSync(\n        path: string,\n        options: ParseOptions & { isModule: false }\n    ): Script;\n    parseFileSync(path: string, options?: ParseOptions): Module;\n    parseFileSync(path: string, options?: ParseOptions): Program {\n        options = options || { syntax: \"ecmascript\" };","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/packages/core/src/index.ts#L213-L249","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst ast = await compiler.parseFile(path, { syntax: 'typescript' });\n\n// after: read in JS, parse the contents (native bindings still required for parse)\nconst { readFile } = require('fs/promises');\nconst ast = await compiler.parse(await readFile(path, 'utf8'), { syntax: 'typescript' });","handlingStrategy":"validation","validationCode":"const { Compiler } = require('@swc/core');\nasync function canUseFileApis() {\n  try {\n    new Compiler().parseSync(''); // native-only probe\n    return true;\n  } catch (e) {\n    if (e instanceof Error && /does not support this interface|Bindings not found|filesystem access/.test(e.message)) {\n      return false; // WASM fallback or broken install — avoid file-based APIs\n    }\n    throw e;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const ast = await compiler.parseFile(path, opts);\n} catch (e) {\n  if (e instanceof Error && /Fallback bindings does not support filesystem access/.test(e.message)) {\n    // on the WASM fallback: read the file in JS and use content-based APIs\n    const src = await require('fs/promises').readFile(path, 'utf8');\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["swc","wasm-fallback","parsefile","filesystem","native-bindings"],"backgroundTag":"wasm-fallback-limitations","analyzedSha":"5176682b65416c6b5de6b47379ae1588ea3ecb3f","analyzedAt":"2026-08-17T16:16:52.067Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}