{"record":{"id":"25df417ddc8ff9f2","repo":"microsoft/TypeScript","slug":"tracing-requires-having-fs-n-original-error-e-m","errorCode":null,"errorMessage":"tracing requires having fs\\n(original error: ${e.message || e})","messagePattern":"tracing requires having fs\\\\n\\(original error: (.+?)\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/compiler/tracing.ts","lineNumber":66,"sourceCode":"\r\n    let legendPath: string | undefined;\r\n    const legend: TraceRecord[] = [];\r\n\r\n    // The actual constraint is that JSON.stringify be able to serialize it without throwing.\r\n    interface Args {\r\n        [key: string]: string | number | boolean | null | undefined | Args | readonly (string | number | boolean | null | undefined | Args)[]; // eslint-disable-line no-restricted-syntax\r\n    }\r\n\r\n    /** Starts tracing for the given project. */\r\n    export function startTracing(tracingMode: Mode, traceDir: string, configFilePath?: string): void {\r\n        Debug.assert(!tracing, \"Tracing already started\");\r\n\r\n        if (fs === undefined) {\r\n            try {\r\n                fs = require(\"fs\");\r\n            }\r\n            catch (e) {\r\n                throw new Error(`tracing requires having fs\\n(original error: ${e.message || e})`);\r\n            }\r\n        }\r\n\r\n        mode = tracingMode;\r\n        typeCatalog.length = 0;\r\n\r\n        if (legendPath === undefined) {\r\n            legendPath = combinePaths(traceDir, \"legend.json\");\r\n        }\r\n\r\n        // Note that writing will fail later on if it exists and is not a directory\r\n        if (!fs.existsSync(traceDir)) {\r\n            fs.mkdirSync(traceDir, { recursive: true });\r\n        }\r\n\r\n        const countPart = mode === \"build\" ? `.${process.pid}-${++traceCount}`\r\n            : mode === \"server\" ? `.${process.pid}`\r\n            : ``;\r","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/microsoft/TypeScript/blob/b465fdbfe175304d9b977da137b2c178ae1091d3/src/compiler/tracing.ts#L48-L84","documentation":"Thrown by `ts.startTracing` when it cannot `require(\"fs\")`. Tracing writes JSON traces to disk and needs the Node `fs` module; if `require(\"fs\")` throws (bundled compiler build, sandboxed/blocked require, non-Node host), `startTracing` aborts. The original error is appended to the message.","triggerScenarios":"Calling `ts.startTracing(mode, traceDir, configPath)` (directly, or via `--traceResolution`/`--generateTrace` style flows that reach it) in an environment where `fs` is unavailable: a webpack/esbuild bundle of the compiler, a sandbox that blocks built-ins, or a custom host without Node's loader.","commonSituations":"Bundling the TS compiler for browser/electron use and then enabling tracing; running the compiler under a custom loader that intercepts `require`; CI sandboxes that restrict built-in modules.","solutions":["Do not enable tracing in environments without `fs` (gate it behind a runtime check).","Provide an `fs` shim or externalize `fs` as a bundler externals entry.","Run tracing in a plain Node process instead of a bundled one.","If you control the call site, check `typeof require !== \"undefined\"` and that `require(\"fs\")` succeeds before calling `startTracing`."],"exampleFix":"// before\nts.startTracing(ts.Mode.All, traceDir, configPath); // throws in a bundle w/o fs\n// after\ntry { require(\"fs\"); ts.startTracing(ts.Mode.All, traceDir, configPath); }\ncatch { /* tracing unavailable in this host; skip */ }","handlingStrategy":"validation","validationCode":"let fsAvailable = false;\ntry { require(\"fs\"); fsAvailable = true; } catch {}\n// only call startTracing when fsAvailable is true","typeGuard":"function canTrace(): boolean { try { require(\"fs\"); return true; } catch { return false; } }","tryCatchPattern":null,"preventionTips":["Mark `fs` as external when bundling the compiler.","Gate tracing behind a runtime `require(\"fs\")` probe.","Run `--generateTrace` in a standard Node process."],"tags":["tracing","runtime","fs","bundler","compiler-api"],"backgroundTag":null,"analyzedSha":"b465fdbfe175304d9b977da137b2c178ae1091d3","analyzedAt":"2026-08-12T05:38:42.698Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}