TypeScript TS2532: Object is possibly 'undefined'

What causes this error

TS2532 fires when strictNullChecks is enabled (or strict mode) and you access a property or call a method on an expression whose type includes undefined. TypeScript tracks control flow narrowing, so this error means there's no prior check that eliminates the undefined possibility from the type at this point in the code.

How to fix it

1. 01

   step 1

   Identify why the value can be undefined

   Check the type of the expression TypeScript flags. Common sources: optional properties (prop?: Type becomes Type | undefined), Map.get() returns T | undefined, Array.find() returns T | undefined, optional function parameters, and optional chaining results.

   interface Config {
     database?: {
       host: string
       port: number
     }
   }
   
   const config: Config = loadConfig()
   // TS2532: Object is possibly 'undefined'
   console.log(config.database.host)  // database is optional

   Copy
2. 02

   step 2

   Add a truthiness or equality check

   The most reliable fix is a control flow narrowing check. TypeScript's control flow analysis removes undefined from the type after an if-check, typeof check, or equality check.

   // Truthiness check
   if (config.database) {
     console.log(config.database.host)  // narrowed to { host: string; port: number }
   }
   
   // Equality check
   if (config.database !== undefined) {
     console.log(config.database.host)  // same narrowing
   }
   
   // typeof check (works for primitives)
   const val: string | undefined = getVal()
   if (typeof val === 'string') {
     console.log(val.toUpperCase())  // narrowed to string
   }

   Copy
3. 03

   step 3

   Use optional chaining for read-only access

   If you only need to read a value and can tolerate undefined as a result, optional chaining (?.) is the most concise fix. It short-circuits to undefined if any part of the chain is nullish.

   // Instead of nested checks:
   const host = config.database?.host  // string | undefined
   const port = config.database?.port  // number | undefined
   
   // Chain deeply:
   const dbName = config.database?.connection?.name  // works at any depth
   
   // Combine with nullish coalescing for defaults:
   const host = config.database?.host ?? 'localhost'
   const port = config.database?.port ?? 5432

   Copy
4. 04

   step 4

   Use non-null assertion only when you have proof

   The ! postfix operator tells TypeScript you guarantee the value isn't null or undefined. Use it only when you have runtime certainty that TypeScript's analysis can't see — for example, after a Map.has() check before Map.get().

   const cache = new Map<string, User>()
   
   // Safe: you just checked .has()
   if (cache.has(userId)) {
     const user = cache.get(userId)!  // OK: we know it exists
   }
   
   // Unsafe: DON'T do this
   const user = cache.get(userId)!  // crashes if userId not in map

   Copy
5. 05

   step 5

   Refactor to eliminate the undefined at its source

   If a value should never actually be undefined at this point in the code, fix the source rather than adding checks at every usage site. Make the property required, provide a default value in the constructor, or use a different API that returns a non-optional type.

   // Before: optional property causes TS2532 everywhere
   interface Config {
     database?: { host: string; port: number }
   }
   
   // After: required with a default
   interface Config {
     database: { host: string; port: number }
   }
   
   const defaultConfig: Config = {
     database: { host: 'localhost', port: 5432 }
   }
   
   function loadConfig(): Config {
     return { ...defaultConfig, ...readConfigFile() }
   }

   Copy

How to verify the fix

• Run tsc --noEmit and confirm TS2532 no longer appears
• Verify that the narrowed code path handles the undefined case (early return, default value, or error throw)
• Check that non-null assertions (!) are backed by a runtime guarantee