How to fix Type 'X[]' must have a '[Symbol.iterator]()' method that returns an iterator in TypeScript

The most common fix is to enable the downlevelIteration compiler option. This tells TypeScript to emit more compliant (but verbose) iteration code for ES5/ES3 targets.

Open your tsconfig.json and add or update the downlevelIteration option:

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true,
    // ... other options
  }
}

This option allows TypeScript to properly handle iteration when targeting older JavaScript versions. Note that enabling this adds helper functions to your compiled output, slightly increasing bundle size.

If you don't need to support very old browsers, the cleanest solution is to target a modern JavaScript version that natively supports iterators.

Update your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2015", // or ES2016, ES2017, ES2018, etc.
    // ... other options
  }
}

ES2015 (ES6) and later versions have native Symbol.iterator support, so TypeScript doesn't need to transform your iteration code. This results in cleaner output and smaller bundle sizes.

If you're trying to spread or iterate over values that might be undefined, add proper null checks or provide fallback values.

Use the nullish coalescing operator to provide a default empty array:

// Before (error-prone)
const combined = [...array1, ...array2];

// After (safe)
const combined = [...(array1 ?? []), ...(array2 ?? [])];

Or use optional chaining with a fallback:

// For function results that might be undefined
const results = [...(getData() ?? [])];

// For optional properties
const items = [...(obj.items ?? [])];

This ensures you're always spreading an actual array, not undefined or null.

If you're working with custom types that should be iterable, ensure they properly implement the iterable interface.

For a custom iterable class:

class CustomIterable<T> implements Iterable<T> {
  private items: T[];

  constructor(items: T[]) {
    this.items = items;
  }

  [Symbol.iterator](): Iterator<T> {
    let index = 0;
    const items = this.items;

    return {
      next(): IteratorResult<T> {
        if (index < items.length) {
          return { value: items[index++], done: false };
        }
        return { value: undefined as any, done: true };
      }
    };
  }
}

// Now this works
const iterable = new CustomIterable([1, 2, 3]);
const array = [...iterable];

Make sure your type implements Iterable<T> and provides the [Symbol.iterator]() method.

If you've enabled downlevelIteration but still get runtime errors in old browsers, you need a Symbol polyfill.

Install core-js:

npm install core-js

Import the Symbol polyfill at your application entry point:

// At the top of your main file (e.g., index.ts)
import 'core-js/features/symbol';
import 'core-js/features/symbol/iterator';

Or if using the full core-js:

import 'core-js/stable';

This ensures that Symbol.iterator exists in the runtime environment, even in browsers that don't support it natively.

Ensure your TypeScript lib configuration includes the appropriate libraries for your target environment.

Check your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES5",
    "lib": ["ES2015", "DOM"],
    "downlevelIteration": true
  }
}

Including "ES2015" in the lib array gives you the type definitions for iterators even when targeting ES5. This allows TypeScript to understand iteration protocols while still outputting ES5-compatible code.

If you don't specify lib, TypeScript defaults to the standard library matching your target, which might not include iterator types.