OpenAI Node SDK 5.0.0: what breaks when you upgrade openai from 4.x

openai 5 is the first release on the rewritten Stainless client. Most of the migration guide never touches application code. What does: beta.chat and runFunctions are gone, fileFromPath and the fetch shims were removed, openai/src no longer resolves, and APIError.headers changed type. The core modules moved under openai/core, with the old paths kept as deprecated re-exports.

What changed

• Calls that stop resolving. client.beta.chat.completions.parse, .stream and .runTools are now under client.chat.completions with the same signatures. runFunctions was removed on both namespaces; runTools replaces it and takes a tools payload rather than a functions one.
• fileFromPath is gone as a named export of openai/uploads, of the package root, and as a static method. Use a runtime stream such as fs.createReadStream.
• Imports that stop resolving. openai/shims/web and openai/shims/node, openai/src and openai/src/index, APIClient from openai/core, and AzureClientOptions from the root.
• APIError.headers is a Web Headers instance. Subscripting it returns undefined at runtime rather than failing to compile.
• A deprecation, not a break. openai/error, /pagination, /resource, /streaming and /uploads moved to openai/core/*. The old paths still resolve. Twelve internal names openai/uploads exported went with the split.

Before and after

The beta.chat rename, on a client held in a variable:

import OpenAI from 'openai';

const client = new OpenAI();

export async function run() {
  const parsed = await client.beta.chat.completions.parse({ model: 'gpt-4o', messages: [] });
  const stream = client.beta.chat.completions.stream({ model: 'gpt-4o', messages: [] });
  const runner = client.beta.chat.completions.runTools({ model: 'gpt-4o', messages: [], tools: [] });
  return { parsed, stream, runner };
}

After npx emendant fix, the beta segment is dropped and nothing else moves:

import OpenAI from 'openai';

const client = new OpenAI();

export async function run() {
  const parsed = await client.chat.completions.parse({ model: 'gpt-4o', messages: [] });
  const stream = client.chat.completions.stream({ model: 'gpt-4o', messages: [] });
  const runner = client.chat.completions.runTools({ model: 'gpt-4o', messages: [], tools: [] });
  return { parsed, stream, runner };
}

The core module move is a specifier rewrite: 'openai/error' becomes 'openai/core/error', import clause untouched. fileFromPath is guidance rather than a patch, because the replacement is not a promise and the await goes with it:

const viaHelper = await fileFromPath('data/training.jsonl');

becomes

const viaHelper = fs.createReadStream('data/training.jsonl');

Migration guidance and its limits

Apply the three deterministic patches: the beta.chat rename, the openai/core rewrite and the openai/src rewrite. The last covers only the two specifiers that mean the package root; a deeper openai/src/... path is reported by nothing.

The assisted changes need a model provider named on the command line or in emendant.json. fileFromPath and the shims are small edits. runFunctions to runTools and APIClient to the concrete client are shape changes, so read the diff.

APIError.headers is reported at medium confidence, because the receiver type cannot be resolved from imports alone. Confirm it, then replace err.headers['x-request-id'] with err.headers.get('x-request-id').

The internal upload helpers and AzureClientOptions are report only: removed, with no documented replacement. The core module move is not urgent, since the old paths still resolve.

What Emendant detects, fixes and verifies

11 changes in openai 5.0.0. 3 patched by a transform, 6 patched only with a model provider you name, 2 report only. Every patch is proved in a copy of your repository before it is offered, and its header names the checks that passed. This table is generated from the feed entry, so it cannot claim more than the entry does.

emendant explain <change-id> prints any row's entry, guidance and sources at the terminal.

Coverage

Snapshot

2026-08-28.1, sequence 11, signed 28 August 2026

Minimum CLI

emendant@0.1.0

Feed entry

feed/npm/openai/5.0.0.json

emendant feed status shows the snapshot your machine holds, and emendant feed update fetches the latest.

Primary sources

Every claim above was checked against these, each pinned to the release rather than to a default branch.

• Release v5.0.0openai/openai-node, the release notes
• Migration guideopenai/openai-node at v5.0.0, 9 sections cited
• openai@5.0.0npm registry, the published package
• openai@4.104.0npm registry, the published package

Scan your repository

Runs locally, reads your lockfile and source, sends nothing anywhere.

npx emendant scan

Then npx emendant fix writes the patches the table says exist. The getting started guide covers the flags and the patch grades.