How to fix Spread syntax may only be applied to Iterable types in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 139 views

This TypeScript error occurs when you try to use the spread operator (...) on a value that TypeScript cannot verify is iterable. Common causes include spreading non-iterable objects, type mismatches, or missing type definitions. The fix involves ensuring the value implements the iterable protocol or adjusting type annotations.

Quick fix

Fixes Spread syntax may only be applied to Iterable types

// Runtime check
const value = getSomeValue();
if (Symbol.iterator in Object(value)) {
  const spread = [...value]; // This should work
} else {
  console.error('Value is not iterable:', value);
}
  1. Verify the value is actually iterable
  2. Add proper type annotations or type assertions
  3. Fix union type issues with type guards
  4. Update third-party library type definitions
typescript — error
// Runtime check
const value = getSomeValue();
if (Symbol.iterator in Object(value)) {
  const spread = [...value]; // This should work
} else {
  console.error('Value is not iterable:', value);
}
Spread syntax may only be applied to Iterable types

What this error means

The "Spread syntax may only be applied to Iterable types" error is a TypeScript compile-time error that occurs when you attempt to use the spread operator (...) on a value that TypeScript's type system cannot guarantee is iterable. In JavaScript/TypeScript, the spread operator can be used in several contexts: 1. Array spreading: `[...array]` 2. Object spreading: `{...object}` 3. Function arguments: `func(...args)` However, TypeScript is stricter than JavaScript at compile time. While JavaScript will throw a runtime error if you try to spread a non-iterable value, TypeScript catches this issue during compilation by checking if the type implements the Iterable interface (has a [Symbol.iterator] method). This error typically appears when TypeScript cannot infer or verify that a value is iterable based on its type annotations, or when working with values that might be iterable at runtime but TypeScript lacks the type information to confirm this.

Typical symptoms

  • TypeScript compilation fails with error TS2488: "Spread syntax may only be applied to Iterable types"
  • The error occurs when using spread operator (...) in array literals, function calls, or object literals
  • Code works at runtime in JavaScript but fails TypeScript compilation
  • Error appears with values from third-party libraries or dynamic data
  • Autocomplete and IntelliSense may not show spread as an available operation

Common causes

  1. Attempting to spread a plain object that doesn't implement the iterable protocol
  2. TypeScript type annotations are too restrictive or incorrect for the actual runtime value
  3. Missing or incomplete type definitions for third-party libraries
  4. Using spread on values with union types where some variants are not iterable
  5. Trying to spread the result of a function that returns a non-iterable type
  6. Generic type parameters that are not constrained to be iterable

How to fix "Spread syntax may only be applied to Iterable types"

1Verify the value is actually iterable

First, check if the value you're trying to spread is actually iterable at runtime. In JavaScript, common iterable types include:
- Arrays: [1, 2, 3]
- Strings: "hello"
- Maps and Sets
- NodeLists and other DOM collections
- Generator functions

Test the value in a JavaScript console or add a runtime check:

typescript
// Runtime check
const value = getSomeValue();
if (Symbol.iterator in Object(value)) {
  const spread = [...value]; // This should work
} else {
  console.error('Value is not iterable:', value);
}
2Add proper type annotations or type assertions

If you know the value is iterable but TypeScript can't infer it, add explicit type annotations or use type assertions:

typescript
// Option 1: Type annotation
const iterableValue: Iterable<number> = getNumbers();
const spreadArray = [...iterableValue];

// Option 2: Type assertion (use cautiously)
const unknownValue = getUnknownValue();
const spreadArray = [...(unknownValue as Iterable<any>)];

// Option 3: Array.isArray() check for arrays
const maybeArray = getMaybeArray();
if (Array.isArray(maybeArray)) {
  const spreadArray = [...maybeArray];
}
3Fix union type issues with type guards

When dealing with union types where some members might not be iterable, use type guards to narrow the type:

typescript
type MaybeIterable = string | number | string[];

function processValue(value: MaybeIterable) {
  // This will error: Spread syntax may only be applied to Iterable types
  // const bad = [...value];

  // Use type guards instead
  if (typeof value === 'string') {
    const chars = [...value]; // Strings are iterable
  } else if (Array.isArray(value)) {
    const items = [...value]; // Arrays are iterable
  } else {
    // Handle non-iterable case
    console.log('Number is not iterable:', value);
  }
}
4Update third-party library type definitions

If the error occurs with a third-party library, check if you need to update or augment the type definitions:

typescript
// If using @types/package-name, update it:
// npm install --save-dev @types/package-name@latest

// Or create a custom type declaration file (e.g., types.d.ts):
declare module 'some-library' {
  export interface SomeReturnType extends Iterable<string> {
    // ... other properties
  }
}

// For missing Symbol.iterator in types, you can augment:
interface SomeLibraryType {
  [Symbol.iterator](): Iterator<string>;
}
5Convert non-iterable values to arrays

For objects that aren't iterable but you want to spread their values, convert them to arrays first:

typescript
// Plain object (not iterable)
const obj = { a: 1, b: 2, c: 3 };

// Convert object values to array
const valuesArray = Object.values(obj);
const spreadFromArray = [...valuesArray]; // Now works: [1, 2, 3]

// Convert object entries to array
const entriesArray = Object.entries(obj);
const spreadEntries = [...entriesArray]; // [['a', 1], ['b', 2], ['c', 3]]

// For array-like objects (has length and numeric indices)
const arrayLike = { 0: 'a', 1: 'b', length: 2 };
const fromArrayLike = Array.from(arrayLike);
const spreadResult = [...fromArrayLike]; // ['a', 'b']
6Use Array.from() as an alternative to spread

When you can't fix the type issues, Array.from() can be a more flexible alternative that works with array-like objects:

typescript
// Array.from() accepts array-like OR iterable objects
const unknownValue = getUnknownValue();

// This might cause TypeScript errors:
// const spread = [...unknownValue];

// This is more flexible:
const array = Array.from(unknownValue);

// Array.from() also accepts a map function
const doubled = Array.from(unknownValue, x => x * 2);

// For objects with iterator protocol issues
const withCustomIterator = {
  data: [1, 2, 3],
  [Symbol.iterator]() {
    return this.data[Symbol.iterator]();
  }
};

const result = Array.from(withCustomIterator); // [1, 2, 3]

Advanced notes

## Understanding Iterable Protocol

The iterable protocol requires an object to have a [Symbol.iterator] method that returns an iterator. The iterator must have a next() method that returns objects with value and done properties.

## TypeScript's Iterable Interface

TypeScript defines iterable types using generic interfaces:

typescript
interface Iterable<T> {
  [Symbol.iterator](): Iterator<T>;
}

interface Iterator<T> {
  next(): IteratorResult<T>;
}

interface IteratorResult<T> {
  value: T;
  done: boolean;
}

## Common Pitfalls

1. Object spreading vs array spreading: Remember that object spreading ({...obj}) doesn't require iterable - it works with any object. The error only occurs for array/iterable spreading.

2. DOM collections: Some DOM collections like NodeList are iterable in modern browsers but TypeScript might need lib: ["dom.iterable"] in tsconfig.

3. Async iterables: For for await...of and spreading async iterables, you need Symbol.asyncIterator and TypeScript's lib: ["es2018.asynciterable"].

4. Generator functions: Generator functions automatically implement the iterable protocol, but their return types need proper annotation.

## tsconfig.json Settings

Ensure your tsconfig.json includes appropriate lib settings:

json
{
  "compilerOptions": {
    "lib": ["es2015", "dom", "dom.iterable"],
    "target": "es2015"
  }
}

The "dom.iterable" lib is particularly important for DOM collections.

Frequently asked questions

What does "Spread syntax may only be applied to Iterable types" mean?
) on a value that TypeScript's type system cannot guarantee is iterable. In JavaScript/TypeScript, the spread operator can be used in several contexts: 1. array] 2.
How do I fix "Spread syntax may only be applied to Iterable types"?
This TypeScript error occurs when you try to use the spread operator (...) on a value that TypeScript cannot verify is iterable. Common causes include spreading non-iterable objects, type mismatches, or missing type definitions. The fix involves ensuring the value implements the iterable protocol or adjusting type annotations.
What causes "Spread syntax may only be applied to Iterable types"?
Attempting to spread a plain object that doesn't implement the iterable protocol TypeScript type annotations are too restrictive or incorrect for the actual runtime value Missing or incomplete type definitions for third-party libraries
Is the "Spread syntax may only be applied to Iterable types" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading