Diagnosing TS2532 and TS18048: A Field Guide to strictNullChecks Errors

You enabled strict (or just strictNullChecks) in tsconfig, and now the compiler is flagging dozens or thousands of lines with "Object is possibly 'undefined'" (TS2532) or "'x' is possibly 'null' or 'undefined'" (TS18048). The useful takeaway: these errors are almost never compiler noise. Each one marks a place where undefined or null can reach an operation that doesn't accept it, and the right fix depends on where the nullable value entered — not on sprinkling ! everywhere.

Recognizing the condition

The pattern is consistent: you access a property, call a method, or do arithmetic on a value whose declared type is a union like string | undefined or User | null. The compiler refuses because one member of the union doesn't support the operation. The errors appear only when strictNullChecks is on; with it off, null and undefined are silently assignable to everything, which is exactly the hole the flag closes. This behavior has been stable since TypeScript 2.0; exact error wording varies slightly by version.

Common causes at a glance

Ordered diagnostic checks

1. Confirm the flag is the gate. Run npx tsc --noEmit --strict from the project root (no special permissions needed). Then temporarily set "strictNullChecks": false in tsconfig and rerun. If the errors vanish, you've confirmed the flag — not a new bug — is what surfaced them.
2. Inspect the declared type. Hover the offending symbol in your editor, or read the full tsc --noEmit output. You need to know whether the union is | undefined, | null, or both — they often come from different sources.
3. Trace where the nullable enters. Follow the type backward: is it an optional parameter? A function return? An initializer like let user: User; left unassigned? The entry point determines the fix.
4. Check for invalidated narrowing. If you already wrote an if (x != null) guard and the error persists inside a callback, narrowing was lost. TypeScript doesn't trust a mutable let to stay narrowed inside closures, because the callback may run after reassignment.

Fixes matched to findings

Optional inputs. Guard early or default at the boundary:

function slugify(title?: string): string {
  const t = title ?? "untitled"; // undefined can no longer reach here
  return t.toLowerCase().replace(/\s+/g, "-");
}

Prefer ?? over || when the value could legitimately be 0 or "" — || treats those as missing too.

Lookup results. Branch on the actual outcome:

const user = usersById.get(id);
if (!user) {
  return { status: 404, body: "not found" };
}
return { status: 200, body: user.name }; // user: User here

Consider enabling "noUncheckedIndexedAccess": true so plain index access (arr[i]) is also typed T | undefined. It produces more errors initially but makes the not-found case impossible to ignore.

Lost narrowing in callbacks. Capture the narrowed value in a const:

if (config.token) {
  const token = config.token; // const keeps the narrowing
  setTimeout(() => refresh(token), 60_000);
}

Genuinely impossible states. If a value is "always set by the time this runs," prefer making that invariant representable — for example, a discriminated union where the "loaded" variant carries a non-null data field — over asserting. When an invariant truly can't be expressed, a non-null assertion (!) or as cast is acceptable, but treat it as a debt marker: rare, and commented with the reason the invariant holds. Neither performs any runtime check.

When to escalate instead of patching

Escalate when the same nullable value forces guards at many call sites. That's a signal the type boundary is wrong, not that you need more guards. Two standard escalations: change the producing API to return a result type (e.g., { ok: true; value: T } | { ok: false; error: string }) so callers must handle failure structurally, or validate once at the system edge — parsing HTTP bodies, environment variables, or file contents into fully non-null domain types — so interior code never sees the union at all.

On a large legacy codebase, flipping strictNullChecks globally can produce thousands of errors at once. Migrate incrementally: enable it per-directory with project references or per-file with // @ts-strict-ignore-style staging, fixing the highest-traffic modules first.

Verifying a fix

Create a minimal reproduction to confirm your diagnosis before and after the change:

// check.ts
export function len(x?: string): number {
  return x.length; // expect TS18048 under --strict
}

Run npx tsc --noEmit --strict check.ts and confirm the error appears. Apply your guard (if (x === undefined) return 0;), rerun, and confirm the error disappears with no cast involved. If it only disappears with ! or as, you silenced the compiler rather than fixing the cause — revisit which finding actually applies.