no-unreachable-loop

Disallow loops with a body that allows only one iteration

no-unreachable-loop

A loop that can never reach its second iteration is usually a mistake. If you only need one iteration, use an if statement instead.

Rule Type: Problem
Fixable: No

Why This Rule Exists

Loops are meant to execute multiple times. If a loop always exits on the first iteration (via break, return, or throw), it should be refactored to use if statements instead.

// This loop can only run once
for (let i = 0; i < arr.length; i++) {
    if (arr[i].name === myName) {
        doSomething(arr[i]);
        // break was supposed to be here!
    }
    break; // Always exits after first iteration
}

Rule Details

This rule detects loops where all code paths exit the loop in the first iteration via:

• break statement
• return statement
• throw statement

It checks these loop types:

• while loops
• do-while loops
• for loops
• for-in loops
• for-of loops

Examples

Incorrect Code

// Unconditional break
while (foo) {
    doSomething(foo);
    foo = foo.parent;
    break; // Always exits after first iteration
}

// All branches return
function verifyList(head) {
    let item = head;
    do {
        if (verify(item)) {
            return true;
        } else {
            return false; // No matter what, we return
        }
    } while (item);
}

// All branches throw or return
function findSomething(arr) {
    for (let i = 0; i < arr.length; i++) {
        if (isSomething(arr[i])) {
            return arr[i];
        } else {
            throw new Error("Doesn't exist."); // Every path exits
        }
    }
}

// Break in all paths
for (const key in obj) {
    if (key.startsWith("_")) {
        break;
    }
    firstKey = key;
    firstValue = obj[key];
    break; // Break either way
}

// Immediate break
for (const foo of bar) {
    if (foo.id === id) {
        doSomething(foo);
    }
    break; // Always break immediately
}

Correct Code

// Loop that can actually iterate
while (foo) {
    doSomething(foo);
    foo = foo.parent; // No break - can continue
}

// Conditional return allows iteration
function verifyList(head) {
    let item = head;
    do {
        if (verify(item)) {
            item = item.next; // Continue to next item
        } else {
            return false; // Only exit on failure
        }
    } while (item);
    return true;
}

// Only returns when found
function findSomething(arr) {
    for (let i = 0; i < arr.length; i++) {
        if (isSomething(arr[i])) {
            return arr[i]; // Exit when found
        }
        // Keep looking
    }
    throw new Error("Doesn't exist."); // After checking all
}

// Continue instead of break
for (const key in obj) {
    if (key.startsWith("_")) {
        continue; // Skip this one, try next
    }
    firstKey = key;
    firstValue = obj[key];
    break; // Break after finding first valid key
}

// Conditional break
for (const foo of bar) {
    if (foo.id === id) {
        doSomething(foo);
        break; // Only break when found
    }
}

Common Refactorings

Replace Loop with If Statement

// Before: Loop that runs once
for (const item of items) {
    if (item.isValid) {
        process(item);
        return true;
    }
    return false;
}

// After: Just use if
const item = items[0];
if (item && item.isValid) {
    process(item);
    return true;
}
return false;

Use Array Methods

// Before: Loop that finds first match
for (const item of items) {
    if (item.id === targetId) {
        return item;
    }
    break; // Bug: should check all items
}

// After: Use find()
return items.find(item => item.id === targetId);

Fix the Break Statement

// Before: Misplaced break
for (let i = 0; i < arr.length; i++) {
    if (arr[i] === target) {
        found = true;
        // break should be here!
    }
    break; // Wrong: exits immediately
}

// After: Break in right place
for (let i = 0; i < arr.length; i++) {
    if (arr[i] === target) {
        found = true;
        break; // Exit when found
    }
}

Replace Break with Continue

// Before: Breaks after skipping one item
for (const item of items) {
    if (item.skip) {
        break; // Bug: should continue, not break
    }
    process(item);
}

// After: Continue to next item
for (const item of items) {
    if (item.skip) {
        continue; // Skip this one, check others
    }
    process(item);
}

Options

ignore

Type: Array<string>

Specify loop types to ignore. Possible values:

• "WhileStatement" - ignore while loops
• "DoWhileStatement" - ignore do-while loops
• "ForStatement" - ignore for loops
• "ForInStatement" - ignore for-in loops
• "ForOfStatement" - ignore for-of loops

// Ignore for-in and for-of loops
{
  "rules": {
    "no-unreachable-loop": ["error", { 
      "ignore": ["ForInStatement", "ForOfStatement"] 
    }]
  }
}

Example: Sometimes you intentionally want to check only the first property:

/* eslint no-unreachable-loop: ["error", { "ignore": ["ForInStatement"] }] */

// Intentionally check only first property
for (const key in obj) {
  hasEnumerableProperties = true;
  break; // OK with ignore option
}

Known Limitations

This rule uses static code path analysis and doesn’t evaluate conditions.

The rule may miss obvious cases:

// This is technically always unreachable, but rule doesn't evaluate `true`
for (let i = 0; i < 10; i++) {
    doSomething(i);
    if (true) { // Static analysis doesn't know this is always true
        break;
    }
}

When Not to Use It

This rule helps catch bugs, but you might disable it if:

1. Your codebase uses loops for single-iteration patterns intentionally
2. You’re using a framework that expects loop syntax for single operations

In most cases, refactoring to if statements will make code clearer.

Intentional Single Iteration

If you really need a loop that runs once:

/* eslint-disable no-unreachable-loop */
for (const key in obj) {
    firstKey = key;
    break; // Intentional: just get first key
}
/* eslint-enable no-unreachable-loop */

// But this is clearer:
const firstKey = Object.keys(obj)[0];

Related Rules

• no-unreachable
• no-constant-condition
• no-unmodified-loop-condition
• for-direction