{"record":{"id":"288759c5ff5f3d38","repo":"ruvnet/ruflo","slug":"failed-to-import-openai","errorCode":null,"errorMessage":"Failed to import OpenAI","messagePattern":"Failed to import OpenAI","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"ruflo/src/ruvocal/src/lib/server/endpoints/openai/endpointOai.ts","lineNumber":73,"sourceCode":"): Promise<Endpoint> {\n\tconst {\n\t\tbaseURL,\n\t\tapiKey,\n\t\tcompletion,\n\t\tmodel,\n\t\tdefaultHeaders,\n\t\tdefaultQuery,\n\t\tmultimodal,\n\t\textraBody,\n\t\tuseCompletionTokens,\n\t\tstreamingSupported,\n\t} = endpointOAIParametersSchema.parse(input);\n\n\tlet OpenAI;\n\ttry {\n\t\tOpenAI = (await import(\"openai\")).OpenAI;\n\t} catch (e) {\n\t\tthrow new Error(\"Failed to import OpenAI\", { cause: e });\n\t}\n\n\t// Store router metadata if captured\n\tlet routerMetadata: { route?: string; model?: string; provider?: string } = {};\n\n\t// Custom fetch wrapper to capture response headers for router metadata\n\tconst customFetch = async (url: RequestInfo, init?: RequestInit): Promise<Response> => {\n\t\tconst response = await fetch(url, init);\n\n\t\t// Capture router headers if present (fallback for non-streaming)\n\t\tconst routeHeader = response.headers.get(\"X-Router-Route\");\n\t\tconst modelHeader = response.headers.get(\"X-Router-Model\");\n\t\tconst providerHeader = response.headers.get(\"x-inference-provider\");\n\n\t\tif (routeHeader && modelHeader) {\n\t\t\trouterMetadata = {\n\t\t\t\troute: routeHeader,\n\t\t\t\tmodel: modelHeader,","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/ruflo/src/ruvocal/src/lib/server/endpoints/openai/endpointOai.ts#L55-L91","documentation":"endpointOai(), the factory for every OpenAI-compatible endpoint in this build, lazily loads the SDK with await import(\"openai\") and wraps any loader failure as Error(\"Failed to import OpenAI\", { cause: e }) (endpointOai.ts:73). The real reason (module not found, ESM/CJS resolution, unsupported Node version) is on err.cause; the wrapper exists so generation code gets one recognizable error instead of raw resolver noise.","triggerScenarios":"First call to endpointOai() (model refresh or first generation) when node cannot resolve/load the openai package: \"openai\" missing from node_modules, corrupted/partial install, a bundler (Vite/rollup SSR build) failing to resolve or bundle it, or an SDK version whose engine requirements exceed the runtime Node.","commonSituations":"Fresh clone without npm install/npm ci; a fork that dropped \"openai\" from package.json; Docker image pruning node_modules incorrectly; pnpm strict hoisting breaking the dynamic import path; Node 16/18 with an ESM-only openai v5+; two conflicting copies of the package after a botched upgrade.","solutions":["Inspect err.cause — it carries the actual resolution/runtime error (e.g. ERR_MODULE_NOT_FOUND, \"not supported\")","Run npm ci (or npm install openai@<version from package.json>) to restore a consistent install","Check node --version against the openai SDK's engines field and upgrade Node if needed","If it only fails in the bundled/built app, mark the package external in the SvelteKit/Vite server config (e.g. ssr.external / server.external including \"openai\") so it is required at runtime from node_modules"],"exampleFix":"// before\n// runtime error: Failed to import OpenAI (cause hidden)\n\n// after (diagnose the cause, then fix the install)\ntry {\n\tawait (await import(\"openai\")).OpenAI;\n} catch (e) {\n\tconsole.error(\"openai SDK failed to load:\", e); // real reason: module not found / engines mismatch\n\tprocess.exit(1);\n}\n// then: npm ci  (or: npm install openai)  and re-run","handlingStrategy":"try-catch","validationCode":"// fail fast at startup instead of at first generation\ntry {\n\tawait import(\"openai\");\n} catch (e) {\n\tconsole.error(\"openai SDK not loadable:\", e);\n\tprocess.exit(1);\n}","typeGuard":"null","tryCatchPattern":"try {\n\tconst { OpenAI } = await import(\"openai\");\n} catch (e) {\n\tthrow new Error(\"openai dependency missing — run npm ci\", { cause: e });\n}","preventionTips":["Keep \"openai\" pinned in package.json and install with npm ci in CI/Docker","Run a post-install smoke check that imports the SDK before accepting a deploy","Verify Node version against the SDK engines field in CI","Mark openai as external in SvelteKit/Vite SSR builds so runtime resolution uses node_modules"],"tags":["openai","dynamic-import","npm","ssr","dependency"],"backgroundTag":"dynamic-import-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}