How to fix 'downlevelIteration' is required for iterating over complex types in TypeScript

What this error means

The 'downlevelIteration' error appears when TypeScript needs to transpile modern JavaScript iteration features to older ECMAScript versions (ES3 or ES5), but encounters types that require more sophisticated iteration handling. "Downleveling" is TypeScript's term for transpiling to an older version of JavaScript. When targeting ES5 or ES3, TypeScript must convert modern iteration primitives—such as for...of loops, array spread syntax ([...array]), argument spread (fn(...args)), and destructuring—into code that works in environments without native Symbol.iterator support. By default, TypeScript uses a simplified downleveling approach that works for basic arrays but fails for: - Iterators and iterables (Map.values(), Set.entries(), generators) - Strings in for...of loops (which iterate by Unicode code point) - Custom objects implementing Symbol.iterator - Type unions that may include iterables When you enable downlevelIteration, TypeScript emits more accurate helper code that checks for Symbol.iterator at runtime and properly handles all iteration scenarios. This comes at the cost of slightly larger bundle sizes due to the additional helper functions.

Typical symptoms

• Compiler error: 'Type X is not an array type or a string type. Use compiler option --downlevelIteration to allow iterating of iterators'
• Error when using spread operator on Maps, Sets, or custom iterables
• for...of loop fails to compile when iterating over complex types
• Array.from() works but spread syntax [...iterable] does not
• Code works fine when targeting ES6+ but breaks with ES5 target
• Error when destructuring iterators or using rest parameters with iterables

Common causes

1. Using for...of loop on iterables (Map, Set, generators) while targeting ES5/ES3
2. Spreading non-array iterables with [...iterable] syntax in ES5 mode
3. TypeScript target is set to 'ES3' or 'ES5' without downlevelIteration enabled
4. Iterating over strings with for...of which requires Symbol.iterator
5. Using argument spread (...args) with iterators in older JS targets
6. Destructuring values from generators or custom iterables
7. Attempting to spread Map.values(), Set.entries(), or similar iterator methods

How to fix "'downlevelIteration' is required for iterating over complex types"

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true
  }
}

npx tsc
# or
npm run build

{
  "compilerOptions": {
    "target": "ES2015",  // or "ES6", "ES2016", etc.
    "module": "commonjs"
  }
}

# ES2015/ES6 supported by:
# - Node.js 6+
# - Chrome 51+
# - Firefox 54+
# - Safari 10+
# - Edge 15+

// BEFORE - causes error with ES5 target
const mySet = new Set([1, 2, 3]);
const array = [...mySet];  // Error: downlevelIteration required

// AFTER - works without downlevelIteration
const array = Array.from(mySet);

// Map values
const myMap = new Map([["a", 1], ["b", 2]]);
// const values = [...myMap.values()];  // Error
const values = Array.from(myMap.values());  // Works

// Strings (iterate by character)
const text = "hello";
// const chars = [...text];  // Error with for...of on strings
const chars = Array.from(text);  // Works

// Custom iterables
function* generator() {
  yield 1;
  yield 2;
}
// const items = [...generator()];  // Error
const items = Array.from(generator());  // Works

// BEFORE - requires downlevelIteration
const mySet = new Set(['a', 'b', 'c']);
for (const item of mySet) {
  console.log(item);
}

// AFTER - works without downlevelIteration
const items = Array.from(mySet);
for (let i = 0; i < items.length; i++) {
  console.log(items[i]);
}

// Or use forEach (if available)
Array.from(mySet).forEach(item => {
  console.log(item);
});

// BEFORE
const myMap = new Map([["key1", "val1"], ["key2", "val2"]]);
for (const [key, value] of myMap) {
  console.log(key, value);
}

// AFTER
myMap.forEach((value, key) => {
  console.log(key, value);
});

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true,
    "importHelpers": true
  }
}

npm install tslib

// Without importHelpers - helpers inlined in every file (larger bundle)
var __read = function() { /* helper code */ };
var array = __read(mySet);

// With importHelpers - single shared import (smaller bundle)
import { __read } from "tslib";
var array = __read(mySet);

Advanced notes

// Source
const items = [...myArray];

// Compiled to ES5 (simple, only works for arrays)
var items = myArray.slice();

// Source
const items = [...myIterable];

// Compiled to ES5 (checks for Symbol.iterator)
var __read = function(o, n) {
  var m = typeof Symbol === "function" && o[Symbol.iterator];
  if (!m) return o;
  var i = m.call(o), r, ar = [], e;
  try {
    while ((n === void 0 || n-- > 0) && !(r = i.next()).done)
      ar.push(r.value);
  } catch (error) { e = { error: error }; }
  finally {
    try {
      if (r && !r.done && (m = i["return"])) m.call(i);
    } finally { if (e) throw e.error; }
  }
  return ar;
};

var items = __read(myIterable);

const sparseArray = [1, , 3];  // Array with hole at index 1

// Without downlevelIteration (uses .concat or .slice)
const copy1 = [...sparseArray];  // [1, empty, 3] - preserves hole

// With downlevelIteration (uses iterator)
const copy2 = [...sparseArray];  // [1, undefined, 3] - fills holes

npm install core-js

// At entry point
import 'core-js/es/symbol';
import 'core-js/es/array/iterator';
import 'core-js/es/map';
import 'core-js/es/set';

<script src="https://polyfill.io/v3/polyfill.min.js?features=Symbol%2CArray.prototype.iterator"></script>

// package.json
{
  "main": "dist/index.js",           // ES5 + downlevelIteration
  "module": "dist/index.esm.js",     // ES2015 modules
  "types": "dist/index.d.ts"
}

Frequently asked questions

What does "'downlevelIteration' is required for iterating over complex types" mean?

The 'downlevelIteration' error appears when TypeScript needs to transpile modern JavaScript iteration features to older ECMAScript versions (ES3 or ES5), but encounters types that require more sophisticated iteration handling. "Downleveling" is TypeScript's term for transpiling to an older version of JavaScript. iterator support.

How do I fix "'downlevelIteration' is required for iterating over complex types"?

This TypeScript error occurs when you try to use modern iteration features (for...of loops, array spread, or destructuring) on complex types while targeting older JavaScript environments (ES3/ES5) without enabling the downlevelIteration compiler option. The fix involves enabling downlevelIteration in tsconfig.json or upgrading your compilation target.

What causes "'downlevelIteration' is required for iterating over complex types"?

Using for...of loop on iterables (Map, Set, generators) while targeting ES5/ES3 Spreading non-array iterables with [...iterable] syntax in ES5 mode TypeScript target is set to 'ES3' or 'ES5' without downlevelIteration enabled

Is the "'downlevelIteration' is required for iterating over complex types" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Duplicate constructor definition

  How to fix 'Duplicate constructor definition' error in TypeScript

  MEDIUM

• Discriminant property 'X' cannot be used for narrowing

  Discriminant property 'X' cannot be used for narrowing

  MEDIUM

• Duplicate identifier 'X'

  How to fix 'Duplicate identifier' error in TypeScript

  MEDIUM

• All destructured elements are unused

  All destructured elements are unused

  LOW

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

Official resources & further reading

• 📚TypeScript Official Documentation
• 📖
  TypeScript TSConfig - downlevelIteration(Official Docs)
• 📖
  TypeScript 2.3 Release Notes - Generators and Iteration(Official Docs)
• Marius Schulz - Downlevel Iteration for ES3/ES5 in TypeScript
• DEV Community - Dealing with the downlevelIteration Error
• Runebook - Understanding and Optimizing Downlevel Iteration
• 🐙
  TypeScript Issue #21617 - Detailed error message on for-of iterators(GitHub)
• Bobby Hadz - IterableIterator is not an array type error