DEV Community: Mahir Faysal

TypeError: unhashable type: 'list' in Python: 10 Causes and Fixes for Dict Keys, Sets, Counter and lru_cache (Tested Examples)

Mahir Faysal — Tue, 10 Nov 2026 03:59:43 +0000

Python raises TypeError: unhashable type: 'list' when you use a list where Python needs a hashable value: as a dictionary key, as an element of a set, in an in check against a set or dict, or as an argument to a function decorated with @lru_cache. Lists can change after they are created, so they have no stable hash. The usual fix is to convert the list to a tuple (or a frozenset when order does not matter) before you use it as a key.

Dicts and sets find items by their hash, and the Python glossary entry for hashable says an object is hashable only if its hash never changes during its lifetime. A list can grow, shrink or change at any moment, so Python refuses to hash it.

Every traceback and output block below comes from real runs on my machine with Python 3.13.5. I also ran the key examples on Python 3.10, 3.12 and 3.14.8, because Python 3.14 rewords this error, and that new wording is worth knowing when you search for it.

In this guide:

What "unhashable type: 'list'" actually means
Cause 1: Using a list as a dictionary key
Cause 2: Putting lists inside a set literal
Cause 3: Calling set.add() with a list
Cause 4: Removing duplicates with set() on a list of lists
Cause 5: An in check against a set or dict
Cause 6: Counter, dict.fromkeys and groupby-style counting
Cause 7: A tuple that contains a list
Cause 8: Passing a list to an @lru_cache or @cache function
Cause 9: unhashable type: 'dict', 'set' and 'bytearray'
Cause 10: A @dataclass instance in a set or as a key
Python 3.14 changed the error message
Why Python will not let you hash a list anyway
Quick fix table for every cause
How to find the list that caused it
Frequently asked questions

What "unhashable type: 'list'" actually means

A hash is an integer that Python computes from a value. Dicts and sets use it like an address, so they can jump straight to the right slot instead of scanning every item. That only works if the hash of a key stays the same for as long as the key lives in the dict.

Here is a quick test of which common values are hashable. It calls hash() on each one and also checks isinstance(v, Hashable):

from collections.abc import Hashable

values = [42, "text", (1, 2), (1, [2]), [1, 2], {"a": 1}, {1}, frozenset({1})]
for v in values:
    try:
        hash(v)
        ok = "hashable"
    except TypeError as e:
        ok = f"TypeError: {e}"
    print(f"{v!r:>16}  isinstance Hashable={isinstance(v, Hashable)!s:5}  hash() -> {ok}")

              42  isinstance Hashable=True   hash() -> hashable
          'text'  isinstance Hashable=True   hash() -> hashable
          (1, 2)  isinstance Hashable=True   hash() -> hashable
        (1, [2])  isinstance Hashable=True   hash() -> TypeError: unhashable type: 'list'
          [1, 2]  isinstance Hashable=False  hash() -> TypeError: unhashable type: 'list'
        {'a': 1}  isinstance Hashable=False  hash() -> TypeError: unhashable type: 'dict'
             {1}  isinstance Hashable=False  hash() -> TypeError: unhashable type: 'set'
  frozenset({1})  isinstance Hashable=True   hash() -> hashable

Numbers, strings, tuples and frozensets are hashable. Lists, dicts and sets are not. Look closely at the fourth line: (1, [2]) passes the isinstance check but still fails hash(), because a tuple is only hashable when everything inside it is hashable. That is why hash() inside a try block is the reliable test, as the collections.abc documentation also hints for Hashable.

Cause 1: Using a list as a dictionary key

This is the classic version. You want to store a price for a combination of values, and the combination happens to be a list:

prices = {}
item = ["apple", "red"]
prices[item] = 1.20

Traceback (most recent call last):
  File "c01_dict_key.py", line 3, in <module>
    prices[item] = 1.20
    ~~~~~~^^^^^^
TypeError: unhashable type: 'list'

The fix is to turn the list into a tuple. Tuples are immutable, so they make good keys, and you can still look the value up with a tuple literal later:

prices = {}
item = ["apple", "red"]
prices[tuple(item)] = 1.20
print(prices)
print(prices[("apple", "red")])

pairs = [[1, 2], [3, 4], [1, 2]]
print(set(map(tuple, pairs)))

# keep the original order while removing duplicates
print([list(t) for t in dict.fromkeys(map(tuple, pairs))])

{('apple', 'red'): 1.2}
1.2
{(1, 2), (3, 4)}
[[1, 2], [3, 4]]

The same file also shows the fix for cause 4 below: set(map(tuple, pairs)) removes duplicate pairs, and dict.fromkeys() does the same while keeping the original order. If you only need to remove duplicates from a flat list, my guide on removing duplicates from a Python list covers more options.

Cause 2: Putting lists inside a set literal

Curly braces with values and no colons create a set, and every set element must be hashable:

points = {[0, 0], [1, 2]}

Traceback (most recent call last):
  File "c02_set_literal.py", line 1, in <module>
    points = {[0, 0], [1, 2]}
             ^^^^^^^^^^^^^^^^
TypeError: unhashable type: 'list'

Write the points as tuples instead: {(0, 0), (1, 2)}.

Cause 3: Calling set.add() with a list

A common pattern for tracking visited items is a seen set. It breaks as soon as the item is a list:

seen = set()
row = [3, 4]
seen.add(row)

Traceback (most recent call last):
  File "c03_set_add.py", line 3, in <module>
    seen.add(row)
    ~~~~~~~~^^^^^
TypeError: unhashable type: 'list'

Use seen.add(tuple(row)), and check membership the same way with tuple(row) in seen. Keep the conversion consistent, because a list and a tuple with the same contents are never equal to each other.

Cause 4: Removing duplicates with set() on a list of lists

set(my_list) is the fastest way to remove duplicates, until the list contains other lists:

pairs = [[1, 2], [3, 4], [1, 2]]
unique = set(pairs)

Traceback (most recent call last):
  File "c04_dedupe.py", line 2, in <module>
    unique = set(pairs)
TypeError: unhashable type: 'list'

Notice that this traceback has no caret line under the code. Python could not point at a single sub-expression, so read the last line carefully. The fix is the map(tuple, pairs) version from cause 1. When the inner order does not matter, so ["a", "b"] and ["b", "a"] count as the same group, use frozenset or a sorted tuple:

groups = [["b", "a"], ["a", "b"], ["c"]]
print({frozenset(g) for g in groups})
print({tuple(sorted(g)) for g in groups})

{frozenset({'b', 'a'}), frozenset({'c'})}
{('a', 'b'), ('c',)}

Cause 5: An in check against a set or dict

This one surprises people because no dict or set is being built. Membership tests on sets and dict keys hash the value on the left:

allowed = {"admin", "editor"}
user_roles = ["editor"]
print(user_roles in allowed)

Traceback (most recent call last):
  File "c05_in_check.py", line 3, in <module>
    print(user_roles in allowed)
          ^^^^^^^^^^^^^^^^^^^^^
TypeError: unhashable type: 'list'

The code asks whether the whole list is one element of allowed, which is almost never what you mean. Usually you want to know whether any or all of the roles are allowed. Set operations answer that directly, and the set types reference lists all of them:

allowed = {"admin", "editor"}
user_roles = ["editor", "viewer"]
print(any(role in allowed for role in user_roles))
print(set(user_roles) & allowed)
print(set(user_roles) <= allowed)

True
{'editor'}
False

& gives the overlap, and <= asks whether every role is in allowed. It returned False here because "viewer" is not allowed.

Cause 6: Counter, dict.fromkeys and groupby-style counting

Anything that counts or groups values uses them as dict keys under the hood. collections.Counter is a dict subclass, so a list of lists fails inside the standard library:

from collections import Counter
orders = [["tea", "milk"], ["coffee"], ["tea", "milk"]]
print(Counter(orders))

Traceback (most recent call last):
  File "c06_counter.py", line 3, in <module>
    print(Counter(orders))
          ~~~~~~~^^^^^^^^
  File "__init__.py", line 611, in __init__
    self.update(iterable, **kwds)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "__init__.py", line 703, in update
    _count_elements(self, iterable)
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^
TypeError: unhashable type: 'list'

The traceback ends inside collections/__init__.py, which makes it look like a library bug. It is not. Walk up to the first line that is your own file, and you will find the list you passed in. Convert each item first, and for dict rows use a JSON string with sorted keys as the key:

import json
from collections import Counter
orders = [["tea", "milk"], ["coffee"], ["tea", "milk"]]
print(Counter(map(tuple, orders)))
rows = [{"a": 1, "b": [1, 2]}, {"b": [1, 2], "a": 1}]
print({json.dumps(r, sort_keys=True) for r in rows})

Counter({('tea', 'milk'): 2, ('coffee',): 1})
{'{"a": 1, "b": [1, 2]}'}

Both dict rows collapsed into one set entry because sort_keys=True makes key order irrelevant. The collections documentation describes Counter as a dict subclass for counting hashable objects, which is the whole rule in one phrase.

Cause 7: A tuple that contains a list

Converting the outer value to a tuple is not enough when there is a list inside it:

key = ("user", [1, 2])
cache = {key: "value"}

Traceback (most recent call last):
  File "c07_tuple_with_list.py", line 2, in <module>
    cache = {key: "value"}
            ^^^^^^^^^^^^^^
TypeError: unhashable type: 'list'

Hashing a tuple hashes every item in it, so the inner list fails. For one level, write ("user", tuple(ids)). For deeply nested data, such as JSON you loaded from an API, a small recursive helper freezes everything at once:

def freeze(obj):
    """Turn nested lists, dicts and sets into hashable tuples/frozensets."""
    if isinstance(obj, dict):
        return tuple(sorted((k, freeze(v)) for k, v in obj.items()))
    if isinstance(obj, (list, tuple)):
        return tuple(freeze(x) for x in obj)
    if isinstance(obj, set):
        return frozenset(freeze(x) for x in obj)
    return obj

record = {"id": 7, "tags": ["new", "sale"], "size": {"w": 2, "h": 3}}
key = freeze(record)
print(key)
print(hash(key) == hash(freeze({"size": {"h": 3, "w": 2}, "tags": ["new", "sale"], "id": 7})))

(('id', 7), ('size', (('h', 3), ('w', 2))), ('tags', ('new', 'sale')))
True

Sorting the dict items means two dicts with the same content but a different key order produce the same frozen key, which the True on the last line confirms. To look at the shape of a nested API response first, the free tools page has browser-based helpers.

Cause 8: Passing a list to an @lru_cache or @cache function

functools.lru_cache stores results in a dict keyed by the arguments, so every argument must be hashable:

from functools import lru_cache

@lru_cache(maxsize=None)
def total(numbers):
    return sum(numbers)

print(total([1, 2, 3]))

Traceback (most recent call last):
  File "c08_lru_cache.py", line 7, in <module>
    print(total([1, 2, 3]))
          ~~~~~^^^^^^^^^^^
TypeError: unhashable type: 'list'

The functools documentation states that the positional and keyword arguments of a cached function must be hashable. A clean fix keeps the public function list-friendly and caches a private tuple version:

from functools import lru_cache

@lru_cache(maxsize=None)
def _total(numbers):
    return sum(numbers)

def total(numbers):
    return _total(tuple(numbers))

print(total([1, 2, 3]))
print(total([1, 2, 3]))
print(_total.cache_info())

6
6
CacheInfo(hits=1, misses=1, maxsize=None, currsize=1)

The second call was a cache hit, as cache_info() shows. The same rule applies to @functools.cache, which is lru_cache(maxsize=None) under another name.

Cause 9: unhashable type: 'dict', 'set' and 'bytearray'

The same error appears with other mutable built-ins. Only the type name in the quotes changes:

for bad in ({"id": 1}, {1, 2}, bytearray(b"ab")):
    try:
        {bad: True}
    except TypeError as e:
        print(type(bad).__name__, "->", e)

dict -> unhashable type: 'dict'
set -> unhashable type: 'set'
bytearray -> unhashable type: 'bytearray'

The fixes follow the same pattern. Use a frozenset instead of a set, bytes instead of a bytearray, and a sorted tuple of items or a JSON string for a dict. If you need a read-only dict that can itself be a key, my post on Python frozendict explains what is available and what is still a proposal.

Cause 10: A @dataclass instance in a set or as a key

This version does not mention lists at all, but it has the same root cause. A regular dataclass is mutable, and it defines __eq__, so Python sets its __hash__ to None:

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

print(Point.__hash__)
visited = {Point(1, 2)}

None
Traceback (most recent call last):
  File "c10_dataclass.py", line 9, in <module>
    visited = {Point(1, 2)}
              ^^^^^^^^^^^^^
TypeError: unhashable type: 'Point'

The first line of output, None, is the hash method that the decorator removed. The dataclasses documentation explains the rules: with eq=True and frozen=True, a __hash__ is generated for you. Freezing the class fixes it and also blocks accidental changes:

from dataclasses import dataclass

@dataclass(frozen=True)
class Point:
    x: int
    y: int

visited = {Point(1, 2), Point(1, 2), Point(3, 4)}
print(visited)
try:
    Point(1, 2).x = 5
except Exception as e:
    print(type(e).__name__, "->", e)

{Point(x=1, y=2), Point(x=3, y=4)}
FrozenInstanceError -> cannot assign to field 'x'

The duplicate Point(1, 2) collapsed into one set entry, and trying to change x raised FrozenInstanceError. Avoid unsafe_hash=True unless you are sure nobody will change the fields after the object goes into a set.

Python 3.14 changed the error message

If you are on Python 3.14, you may never see the exact text unhashable type: 'list' as the whole message. Here is cause 1 on three versions:

Python 3.10:

Traceback (most recent call last):
  File "c01_dict_key.py", line 3, in <module>
    prices[item] = 1.20
TypeError: unhashable type: 'list'

Python 3.12:

Traceback (most recent call last):
  File "c01_dict_key.py", line 3, in <module>
    prices[item] = 1.20
    ~~~~~~^^^^^^
TypeError: unhashable type: 'list'

Python 3.14.8:

Traceback (most recent call last):
  File "c01_dict_key.py", line 3, in <module>
    prices[item] = 1.20
    ~~~~~~^^^^^^
TypeError: cannot use 'list' as a dict key (unhashable type: 'list')

Python 3.14 now says what you were trying to do with the list. Set cases get their own wording too, while lru_cache still uses the short form:

-- c03_set_add.py --
TypeError: cannot use 'list' as a set element (unhashable type: 'list')
-- c04_dedupe.py --
TypeError: cannot use 'list' as a set element (unhashable type: 'list')
-- c08_lru_cache.py --
TypeError: unhashable type: 'list'

The What's New in Python 3.14 page lists this as an improved error message. Python 3.10 also lacks the ~~~^^^ markers, which arrived in 3.11. The cause and the fix are the same on every version.

Why Python will not let you hash a list anyway

You might wonder why Python does not just hash the current contents of the list. The next example shows what goes wrong when you do that yourself with a custom class:

class Box:
    def __init__(self, items):
        self.items = items
    def __eq__(self, other):
        return self.items == other.items
    def __hash__(self):
        return hash(tuple(self.items))

b = Box([1, 2])
s = {b}
b.items.append(3)
print(b in s)
print(len(s), Box([1, 2, 3]) in s)

False
1 False

After append(3), the object is still in the set, but the set cannot find it, because it looks in the slot for the new hash while the object sits in the slot for the old one. Even a fresh Box([1, 2, 3]) is not found. The data model reference for __hash__ warns about exactly this: mutable objects that compare by value should not be hashable.

Quick fix table for every cause

Use this as a checklist when the traceback points at a line and you are not sure which pattern you hit:

Where the error comes from	Typical line	Fix
List as a dict key	`prices[["apple", "red"]] = 1.2`	Use `tuple(item)` as the key
List inside a set literal	`{[0, 0], [1, 2]}`	Use tuples: `{(0, 0), (1, 2)}`
set.add() with a list	`seen.add(row)`	`seen.add(tuple(row))`
set() on a list of lists	`set(pairs)`	`set(map(tuple, pairs))`
in check against a set or dict	`user_roles in allowed`	`any(r in allowed for r in user_roles)`
Counter or dict.fromkeys on lists	`Counter(orders)`	`Counter(map(tuple, orders))`
Tuple that contains a list	`{("user", [1, 2]): v}`	Convert the inner list too
@lru_cache / @cache argument	`total([1, 2, 3])`	Pass a tuple, or wrap the function
dict, set or bytearray as a key	`{{'id': 1}: True}`	frozenset, sorted tuple of items or json.dumps
@dataclass instance in a set	`{Point(1, 2)}`	`@dataclass(frozen=True)`

Picking between tuple and frozenset comes down to one question: does order or duplication matter? If yes, use a tuple. If not, use a frozenset. My comparison of list vs tuple vs set vs dict goes deeper on that choice.

How to find the list that caused it

When the line has several values, these steps find the culprit quickly:

Read the last traceback line that points at your own file, not the standard library.
Look at the caret markers on Python 3.11+. They underline the key or element being hashed.
Print type(x) for each candidate key. Data from json.load(), CSV splits and str.split() is always a list.
Wrap the suspicious value in hash() on its own line to confirm.

If the problem is a missing key rather than an unhashable one, see my guide to KeyError in Python.

Frequently asked questions

How do I fix TypeError: unhashable type: 'list'?

Convert the list to a tuple before using it as a dict key or set element, for example d[tuple(items)] = value. Use frozenset when order does not matter, and convert nested lists too.

Why are lists unhashable in Python?

A list can change after it is created, so its hash would change too. Dicts and sets rely on hashes that never change, so Python makes lists unhashable on purpose.

Can a tuple be unhashable?

Yes. A tuple is hashable only if every item in it is hashable. hash((1, [2])) raises TypeError: unhashable type: 'list' because of the list inside.

What does 'cannot use list as a dict key' mean?

It is the Python 3.14 wording of the same error. Python 3.14 adds context, so you see cannot use 'list' as a dict key (unhashable type: 'list'). The fix is the same.

How do I remove duplicate lists from a list?

Use set(map(tuple, pairs)) if order does not matter, or [list(t) for t in dict.fromkeys(map(tuple, pairs))] to keep the original order. Both convert each inner list to a tuple first.

How do I use lru_cache with a list argument?

Convert the list to a tuple before calling the cached function. A small wrapper that calls the cached version with tuple(numbers) keeps the public function easy to use.

How do I make a dataclass hashable?

Use @dataclass(frozen=True). With eq=True and frozen=True, the decorator generates __hash__ for you, so instances can go into sets and be used as dict keys.

Last checked: 9 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

Python Assignment vs Shallow Copy vs Deep Copy (copy vs deepcopy): Differences, Nested Lists and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:50:36 +0000

In Python, b = a does not copy anything: it gives the same object a second name, so a change through one name shows up in the other. A shallow copy (a.copy(), a[:], list(a), dict(a) or copy.copy(a)) creates a new outer container, but the lists and dicts inside it are still shared. copy.deepcopy(a) copies the container and everything inside it, recursively, so the result is fully independent.

If you have ever changed a "copy" of a list and watched the original change too, one of these three behaviours is the reason. The copy module documentation defines shallow and deep copies in two sentences. Seeing it happen is what makes it stick.

Every example below ran on my machine with Python 3.13.5, and the copy.replace() example also ran on 3.11, 3.12 and 3.14. The output blocks are pasted straight from those runs, nothing retyped.

In this guide:

Assignment: two names, one object
Shallow copy: a new box with the same contents
Shallow copies of lists: slicing, list() and copy()
Deep copy: copy.deepcopy copies everything inside
Assignment vs shallow copy vs deep copy compared
The [[0] * 3] * 3 trap
Copying class instances
When deepcopy fails, and how __deepcopy__ fixes it
Shared references and self-referencing lists
Tuples, strings and other immutables
The bug you get without copying: functions that change their arguments
copy.replace() in Python 3.13: copy with changes
deepcopy vs a JSON round trip
How fast is each one?
Which one should you use?
Frequently asked questions

Assignment: two names, one object

Start with the case that catches beginners most often:

cart = ["apple", "bread"]
backup = cart              # assignment: a second name, same list

backup.append("milk")

print("cart:  ", cart)
print("backup:", backup)
print("same object?", backup is cart, id(backup) == id(cart))

cart:   ['apple', 'bread', 'milk']
backup: ['apple', 'bread', 'milk']
same object? True True

backup was never a backup. Assignment binds a name to an existing object, and is plus id() both confirm that the two names point to the same list. The Python data model describes this: every object has an identity, and names are just references to it.

This is not a bug. It is how Python avoids copying large data every time you pass it around. You only need to care when the object is mutable, like a list, dict, set or most class instances.

Shallow copy: a new box with the same contents

A shallow copy creates a new outer object and fills it with references to the same inner objects. For dictionaries there are four common ways to do it, and my test shows they all behave the same:

import copy

scores = {"maths": [70, 80], "art": [90]}

a = scores.copy()          # dict method
b = dict(scores)           # constructor
c = {**scores}             # unpacking
d = copy.copy(scores)      # copy module

for name, obj in [("copy()", a), ("dict()", b), ("{**}", c), ("copy.copy", d)]:
    print(f"{name:10} new dict? {obj is not scores}  inner list shared? {obj['maths'] is scores['maths']}")

a["art"] = [100]           # replacing a key: only the copy changes
a["maths"].append(99)      # mutating a shared inner list: both change

print("original:", scores)
print("copy:    ", a)

copy()     new dict? True  inner list shared? True
dict()     new dict? True  inner list shared? True
{**}       new dict? True  inner list shared? True
copy.copy  new dict? True  inner list shared? True
original: {'maths': [70, 80, 99], 'art': [90]}
copy:     {'maths': [70, 80, 99], 'art': [100]}

Two things happened. Replacing a["art"] with a new list changed only the copy, because the copy has its own outer dict. But a["maths"].append(99) changed both, because "maths" in both dicts still points to the same inner list. The built-in types reference lists dict.copy() and list.copy() as shallow copies for exactly this reason.

Shallow copies of lists: slicing, list() and copy()

Lists behave the same way. grid[:], list(grid) and grid.copy() all produce a new outer list that shares its rows:

grid = [[0, 0], [0, 0]]

s1 = grid[:]
s2 = list(grid)
s3 = grid.copy()

s1[0][0] = 1               # changes the shared row
s1.append([9, 9])          # changes only s1's outer list

print("grid:", grid)
print("s1:  ", s1)
print("s2:  ", s2)
print("rows shared?", s1[1] is grid[1], s2[1] is grid[1], s3[1] is grid[1])

grid: [[1, 0], [0, 0]]
s1:   [[1, 0], [0, 0], [9, 9]]
s2:   [[1, 0], [0, 0]]
rows shared? True True True

Appending [9, 9] only affected s1, but writing to s1[0][0] changed the original grid and every other copy, because they all hold the same row objects. If your list holds only numbers, strings or tuples, a shallow copy is all you need, since those values cannot change in place. My guide to list vs tuple vs set vs dict covers which types are mutable.

Deep copy: copy.deepcopy copies everything inside

copy.deepcopy() walks through the object and copies every mutable thing it finds:

import copy

config = {"db": {"host": "localhost", "ports": [5432]}, "debug": False}

deep = copy.deepcopy(config)
print("inner dict shared?  ", deep["db"] is config["db"])
print("inner list shared?  ", deep["db"]["ports"] is config["db"]["ports"])
print("host string shared? ", deep["db"]["host"] is config["db"]["host"])

deep["db"]["ports"].append(6543)
deep["db"]["host"] = "prod.internal"

print("original:", config)
print("deep:    ", deep)

inner dict shared?   False
inner list shared?   False
host string shared?  True
original: {'db': {'host': 'localhost', 'ports': [5432]}, 'debug': False}
deep:     {'db': {'host': 'prod.internal', 'ports': [5432, 6543]}, 'debug': False}

The inner dict and inner list are new objects, so changing the copy left the original config alone. Notice the third line, though: the host string was not copied. Strings, numbers, booleans and other immutable values are safe to share, so deepcopy simply reuses them. That is why a deep copy is not twice the memory of the original.

Assignment vs shallow copy vs deep copy compared

Here is the whole difference in one table. The speed column comes from the timing test further down, copying a list of 1,000 small dicts.

Method	New outer object?	Nested objects	Speed (my test)	Use it when
`b = a` (assignment)	No, same object	Shared	Instant	You want a second name for the same data
`a.copy()`, `a[:]`, `list(a)`, `dict(a)`, `{**a}`	Yes	Shared	About 1.6 microseconds	The data is flat, or you only add, remove or replace top-level items
`copy.copy(a)`	Yes	Shared	About 1.7 microseconds	Generic shallow copy of any object, including class instances
`copy.deepcopy(a)`	Yes	New copies, recursively	About 2,376 microseconds	You will change nested lists, dicts or objects independently
`json.loads(json.dumps(a))`	Yes	New copies	About 960 microseconds	Only for plain JSON data; loses tuples, sets and dates

The short rule: if you are about to change something inside the copy, not just the copy itself, you need deepcopy. And if you want to sanity-check data while you debug, such as formatting JSON or comparing two outputs, my free browser tools work right in your browser.

The [[0] * 3] * 3 trap

This is the shallow-copy bug in disguise, and it shows up in grid, board and matrix code all the time:

board = [[0] * 3] * 3      # looks like 3 rows, really 1 row three times
board[0][0] = "X"
print(board)
print("rows are the same object?", board[0] is board[1] is board[2])

board = [[0] * 3 for _ in range(3)]
board[0][0] = "X"
print(board)

[['X', 0, 0], ['X', 0, 0], ['X', 0, 0]]
rows are the same object? True
[['X', 0, 0], [0, 0, 0], [0, 0, 0]]

Multiplying a list repeats references, so [[0] * 3] * 3 holds the same row three times. Setting one cell put an X in every row. The list comprehension builds a new row on each pass, which is the fix the official Python programming FAQ recommends for multidimensional lists.

Copying class instances

The copy module works on your own classes too, and the same shallow-versus-deep rule applies to their attributes:

import copy

class Player:
    def __init__(self, name, items):
        self.name = name
        self.items = items

p1 = Player("Ana", ["sword"])
p2 = copy.copy(p1)
p3 = copy.deepcopy(p1)

p2.name = "Ben"
p2.items.append("shield")

print("p1:", p1.name, p1.items)
print("p2:", p2.name, p2.items)
print("p3:", p3.name, p3.items)

p1: Ana ['sword', 'shield']
p2: Ben ['sword', 'shield']
p3: Ana ['sword']

copy.copy(p1) made a new Player, so renaming p2 did not rename p1. But the items list was shared, so Ben's shield also appeared in Ana's inventory. The deep copy p3 was taken before the change and kept its own list. This is a common source of "why did every enemy get the same power-up?" bugs in games and simulations.

When deepcopy fails, and how deepcopy fixes it

deepcopy cannot copy everything. Locks, open files, sockets and database connections hold operating-system resources, and copying them makes no sense:

import copy, threading

class Cache:
    def __init__(self):
        self.data = {"a": [1]}
        self.lock = threading.Lock()

try:
    copy.deepcopy(Cache())
except TypeError as e:
    print("TypeError:", e)

class SafeCache(Cache):
    def __deepcopy__(self, memo):
        new = SafeCache()                       # fresh lock
        new.data = copy.deepcopy(self.data, memo)
        return new

c1 = SafeCache()
c2 = copy.deepcopy(c1)
c2.data["a"].append(2)
print("c1.data:", c1.data, "c2.data:", c2.data, "locks differ:", c1.lock is not c2.lock)

TypeError: cannot pickle '_thread.lock' object
c1.data: {'a': [1]} c2.data: {'a': [1, 2]} locks differ: True

The error mentions pickle because deepcopy falls back on the same object-reduction protocol that the pickle module uses. The fix is to define __deepcopy__ on your class: create a fresh lock, deep-copy only the data, and pass the memo dictionary along so shared references are handled correctly. After that the copy worked and each object got its own lock.

Shared references and self-referencing lists

Two details make deepcopy smarter than a simple recursive loop:

import copy

shared = [1, 2]
pair = [shared, shared]
d = copy.deepcopy(pair)
print("inside the copy, still one shared list?", d[0] is d[1])
print("but separate from the original?", d[0] is not shared)

loop = [1]
loop.append(loop)          # a list that contains itself
print("loop:", loop)
dl = copy.deepcopy(loop)
print("deep copy of loop:", dl, "| points to itself?", dl[1] is dl)

inside the copy, still one shared list? True
but separate from the original? True
loop: [1, [...]]
deep copy of loop: [1, [...]] | points to itself? True

First, if the same list appears twice in the original, the deep copy also has one list appearing twice, not two separate lists. Second, a list that contains itself does not cause infinite recursion. Both come from the memo dictionary, which remembers every object already copied during the current call.

Tuples, strings and other immutables

For immutable objects, copying is mostly pointless, and Python knows it:

import copy

t = (1, 2, "three")
print("tuple copy is same object?", copy.copy(t) is t, copy.deepcopy(t) is t)

t2 = (1, [2, 3])
dt2 = copy.deepcopy(t2)
print("tuple holding a list, deepcopy new?", dt2 is not t2, "| inner list new?", dt2[1] is not t2[1])

s = "hello"
print("str copy same object?", copy.copy(s) is s, copy.deepcopy(s) is s)

tuple copy is same object? True True
tuple holding a list, deepcopy new? True | inner list new? True
str copy same object? True True

copy.copy and copy.deepcopy returned the very same tuple and string. The exception is a tuple that holds something mutable, like a list. A deep copy then has to build a new tuple, because the list inside it needs to be copied.

The bug you get without copying: functions that change their arguments

Python passes references into functions, so a function that modifies a list in place also changes the caller's list:

def add_tax(prices):
    for i in range(len(prices)):
        prices[i] = round(prices[i] * 1.2, 2)
    return prices

basket = [10.0, 5.5]
with_tax = add_tax(basket)
print("basket:  ", basket, "<- changed by the function")

def add_tax_safe(prices):
    return [round(p * 1.2, 2) for p in prices]

basket = [10.0, 5.5]
with_tax = add_tax_safe(basket)
print("basket:  ", basket)
print("with_tax:", with_tax)

basket:   [12.0, 6.6] <- changed by the function
basket:   [10.0, 5.5]
with_tax: [12.0, 6.6]

You could fix the first version with prices = prices.copy() at the top, but returning a new list with a comprehension is cleaner and needs no copy at all. My list comprehension examples show more patterns like this. As a habit, either change the argument in place and return None, like list.sort() does, or leave it untouched and return a new object, like sorted(). Mixing the two causes surprises.

copy.replace() in Python 3.13: copy with changes

Python 3.13 added copy.replace(), which makes a copy of an object with some fields changed. It works on dataclasses, named tuples and any class with a __replace__ method, and it is perfect for frozen, immutable objects:

import copy, sys
from dataclasses import dataclass, replace

@dataclass(frozen=True)
class Point:
    x: int
    y: int

p = Point(1, 2)
print(sys.version.split()[0])
print("dataclasses.replace:", replace(p, y=5))
print("copy.replace:       ", copy.replace(p, x=10))
print("original unchanged: ", p)

3.13.5
dataclasses.replace: Point(x=1, y=5)
copy.replace:        Point(x=10, y=2)
original unchanged:  Point(x=1, y=2)

The What's New in Python 3.13 page lists it under the copy module. On older versions it simply does not exist. Here is the same file on Python 3.11:

3.11.17
dataclasses.replace: Point(x=1, y=5)
Traceback (most recent call last):
  File "e10_replace.py", line 12, in <module>
    print("copy.replace:       ", copy.replace(p, x=10))
                                  ^^^^^^^^^^^^
AttributeError: module 'copy' has no attribute 'replace'
[exit 1]

Python 3.12.16 failed the same way, and 3.14.8 matched 3.13. On 3.12 or older, use dataclasses.replace(), which did the same job in every version I tested.

deepcopy vs a JSON round trip

Some tutorials suggest json.loads(json.dumps(data)) as a "faster deep copy". It does produce independent nested objects, but it only understands JSON types:

import copy, json
from datetime import date

data = {"when": date(2026, 11, 9), "tags": {"a", "b"}, "n": (1, 2)}
print("deepcopy:", copy.deepcopy(data) == data)
try:
    json.loads(json.dumps(data))
except TypeError as e:
    print("json round trip: TypeError:", e)

simple = {"n": (1, 2)}
print("json turns tuples into lists:", json.loads(json.dumps(simple)))

deepcopy: True
json round trip: TypeError: Object of type date is not JSON serializable
json turns tuples into lists: {'n': [1, 2]}

A date crashed it, and the tuple silently came back as a list. Use JSON for saving data, as in my guide to writing JSON to a file, and use deepcopy for copying it.

How fast is each one?

I timed each approach on the same data with the timeit module, taking the best of five rounds:

import copy, json, timeit, sys, platform

data = [{"id": i, "tags": ["a", "b"], "meta": {"score": i * 1.5}} for i in range(1000)]

tests = {
    "assignment (b = a)": lambda: data,
    "list.copy() (shallow)": lambda: data.copy(),
    "copy.copy (shallow)": lambda: copy.copy(data),
    "json loads/dumps": lambda: json.loads(json.dumps(data)),
    "copy.deepcopy": lambda: copy.deepcopy(data),
}
print(f"Python {sys.version.split()[0]}, {platform.machine()}, list of 1,000 small dicts, best of 5 x 200 runs")
for name, fn in tests.items():
    best = min(timeit.repeat(fn, number=200, repeat=5)) / 200
    print(f"{name:24} {best * 1e6:10.1f} microseconds per copy")

Python 3.13.5, x86_64, list of 1,000 small dicts, best of 5 x 200 runs
assignment (b = a)              0.0 microseconds per copy
list.copy() (shallow)           1.6 microseconds per copy
copy.copy (shallow)             1.7 microseconds per copy
json loads/dumps              947.0 microseconds per copy
copy.deepcopy                2420.0 microseconds per copy

The exact numbers depend on the machine, but the pattern is what matters. A shallow copy of this list took about 1.6 microseconds. A deep copy took about 2,376, more than a thousand times longer, because it visits all 1,000 dicts and their inner lists. The JSON round trip was faster here, but it fails on the types shown above. Deep-copy when you need independence, not by default.

Which one should you use?

Assignment when you want another name for the same data, for example passing a list into a function that should update it.
Shallow copy when the data is flat (numbers, strings, tuples) or you only add, remove or replace top-level items.
copy.deepcopy when the copy will change nested lists, dicts or objects and the original must not.
copy.replace or dataclasses.replace when you work with immutable records and want a modified version.
A custom __deepcopy__ when your class holds locks, files or connections.

If you also write JavaScript, the same three levels exist there, with structuredClone() as the deep copy. I compared them in how to deep copy an object in JavaScript.

Frequently asked questions

What is the difference between copy and deepcopy in Python?

copy.copy creates a new outer object but keeps references to the same nested objects. copy.deepcopy creates a new outer object and recursively copies every mutable object inside it, so changes to nested data do not affect the original.

Does b = a copy a list in Python?

No. Assignment makes b another name for the same list. In my test, b is a returned True and appending through b changed a as well.

Is list.copy() a deep copy?

No. list.copy(), slicing with [:] and list() are all shallow. The new list shares its inner lists and dicts with the original, so changing a nested item affects both.

Why does changing one row change every row in my 2D list?

You probably built it with [[0] * 3] * 3, which repeats one row object three times. Build it with a list comprehension, [[0] * 3 for _ in range(3)], so each row is a separate list.

Why does deepcopy fail with cannot pickle _thread.lock object?

deepcopy reached an object such as a lock, file or connection that cannot be copied. Define __deepcopy__ on the class to create a fresh resource and deep-copy only the data.

Is deepcopy slow?

It is much slower than a shallow copy. In my test on a list of 1,000 small dicts, a shallow copy took about 1.6 microseconds and deepcopy about 2,376 microseconds. Use it when you need independent nested data.

Can I use json.loads(json.dumps(x)) instead of deepcopy?

Only for plain JSON data. In my test it raised TypeError for a date and turned a tuple into a list. deepcopy handled both correctly.

Last checked: 9 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

Type 'X' is not assignable to type 'Y' in TypeScript (TS2322, TS2345): 10 Causes and Fixes (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:50:09 +0000

TypeScript shows Type 'X' is not assignable to type 'Y' (TS2322), or Argument of type 'X' is not assignable to parameter of type 'Y' (TS2345), when the value on the right could hold something the type on the left does not allow. Most often that something is undefined, null, a plain string where a literal union was expected, or an un-awaited Promise. Fix it by narrowing the value, converting it, or correcting the declared type. Do not reach for as or any first.

This is the TypeScript error I hit most, and its long message makes it easy to read the wrong half. The first line names the two types. The indented lines underneath explain exactly which part does not fit. Once you know how to read that chain, most fixes take seconds.

I reproduced every case below on my machine with TypeScript 7.0.2 (the new native compiler) and Node v24.22.1, compiling each file on its own with --strict --noEmit. Two cases were also checked on TypeScript 5.9.3, and the messages were identical. Everything inside the output blocks is copied straight from those runs.

In this guide:

What the error looks like
Why TypeScript refuses the assignment
TypeScript 7 made this error more common
The 10 causes at a glance
1. An optional property or parameter (string | undefined)
2. A string from a form or URL passed where a number is expected
3. A plain string where a literal union is expected
4. A required property is missing from an object
5. A DOM query that can return null
6. Forgetting to await a Promise
7. An array with mixed types
8. A readonly array passed to a function that expects a mutable one
9. React useState(null) without a type
10. Returning a concrete value from a generic function
The fixes in one file, compiled and run
Why "as" is the wrong first fix (and satisfies is better)
How to fix it fast: a checklist
Frequently asked questions

What the error looks like

Here is the smallest example: an optional property assigned to a variable typed as string.

interface User {
  name: string;
  nickname?: string;
}

function greet(user: User): string {
  const label: string = user.nickname;
  return `Hi ${label}`;
}

c01_optional.ts(7,9): error TS2322: Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.

Read the output in three parts. c01_optional.ts(7,9) is the file, line and column. TS2322 is the error code you can search for. The indented line is the important one: TypeScript tells you that the undefined member of the union is the piece that does not fit into string.

On longer errors, always read to the last indented line. That is the actual conflict.

Why TypeScript refuses the assignment

TypeScript checks assignability structurally. A value of type A can go into a slot of type B only if every possible A is also a valid B. string | undefined fails that test because one possible value, undefined, is not a string. The type compatibility chapter of the handbook describes these rules in detail.

The same check runs in three places, which is why you see slightly different codes:

TS2322 for assignments, return values and variable declarations.
TS2345 for function arguments.
TS2741, TS2353 and TS4104 for more specific object and readonly mismatches that come from the same rule.

TypeScript 7 made this error more common

One important 2026 change: the TypeScript 7.0 release turns strict on by default. In my test, the same file with no flags at all still failed on TS 7.0.2, passed on TS 7.0.2 with --strict false, and passed on TS 5.9.3 with default options. So if you just upgraded and dozens of these errors appeared, that is the reason.

c01_optional.ts(7,9): error TS2322: Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.

With --strict false on TS 7.0.2 and with default options on TS 5.9.3, the same file printed nothing and exited with code 0. The errors were always real bugs waiting to happen; strict mode just stopped hiding them.

The 10 causes at a glance

Find the row that matches your message.

#	What you see	Code	Usual fix
1	`'string	undefined' `is not assignable to` 'string'`	TS2322
2	Argument of type `'string'` ... parameter of type `'number'`	TS2345	Convert with `Number()` and validate
3	Argument of type `'string'` ... parameter of type `'Direction'`	TS2345	`const`, a type annotation, `as const` or `satisfies`
4	Property `'price'` is missing ... but required	TS2741	Add the property or make it optional
5	`'HTMLInputElement	null'` is not assignable	TS2322
6	`'Promise<number>'` is not assignable to `'number'`	TS2322	`await` the call
7	`'(string	number)[]' `is not assignable to` 'string[]'`	TS2322
8	`readonly` ... cannot be assigned to the mutable type	TS4104	Accept `readonly string[]`
9	... not assignable to parameter of type `'SetStateAction<null>'`	TS2345	`useState<User
10	{% raw %}`'T'` could be instantiated with an arbitrary type	TS2322	Let the caller pass the default

1. An optional property or parameter (string | undefined)

This is the example above. nickname?: string really means string | undefined, so it cannot go straight into a string. The same happens with optional function parameters, Array.prototype.find(), Map.get() and environment variables like process.env.API_URL.

Give it a fallback with the nullish coalescing operator ??, or check it first:

const label: string = user.nickname ?? user.name;

If you are unsure whether the value should ever be missing, the real question is about your data, not your types. My guide to null vs undefined in JavaScript covers when each one shows up.

2. A string from a form or URL passed where a number is expected

Values from inputs, query strings, localStorage and CSV files are always strings, even when they look like numbers.

function addVat(price: number): number {
  return price * 1.2;
}

const input = "49.99"; // e.g. from a form field or URL param
addVat(input);

c02_input_string.ts(6,8): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Convert at the edge of your program and check the result, so the rest of your code only sees real numbers:

const price = Number(input);
if (!Number.isNaN(price)) addVat(price);

Avoid input as unknown as number. It compiles, but at runtime "49.99" * 1.2 only works by accident, and "49.99" + 1 gives "49.991".

3. A plain string where a literal union is expected

This one confuses almost everyone the first time. The value is literally "left", yet TypeScript still complains:

type Direction = "left" | "right";

function move(dir: Direction) {
  console.log("moving", dir);
}

let dir = "left";
move(dir);

const config = { dir: "right" };
move(config.dir);

c03_literal_widening.ts(8,6): error TS2345: Argument of type 'string' is not assignable to parameter of type 'Direction'.
c03_literal_widening.ts(11,6): error TS2345: Argument of type 'string' is not assignable to parameter of type 'Direction'.

The reason is widening. A let variable can be reassigned, so TypeScript infers string, not "left". Object properties are mutable too, so config.dir also widens to string. The handbook section on literal types and literal inference explains the rule.

Any of these fixes passed in my test file:

const dir = "left";
move(dir);
let dir2: Direction = "left";
move(dir2);
const config = { dir: "right" } as const;
move(config.dir);
const config2 = { dir: "right" } satisfies { dir: Direction };
move(config2.dir);

I prefer satisfies for config objects. It checks the object against the type and still keeps the narrow literal types.

4. A required property is missing from an object

When an object literal does not match its interface, TypeScript names the missing property directly:

interface Product {
  id: number;
  title: string;
  price: number;
}

const p: Product = { id: 1, title: "Mug" };

c04_missing_prop.ts(7,7): error TS2741: Property 'price' is missing in type '{ id: number; title: string; }' but required in type 'Product'.

Either add the property, or, if it truly is optional in your data, change the interface to price?: number. Making it optional just moves the problem to every place that reads price, so only do it when the data really can be missing. If you are deciding how to model these shapes in the first place, see TypeScript interface vs type.

5. A DOM query that can return null

document.querySelector() and getElementById() return null when nothing matches, and the DOM types say so:

const input: HTMLInputElement = document.querySelector("#email");

c05_null_dom.ts(1,7): error TS2322: Type 'HTMLInputElement | null' is not assignable to type 'HTMLInputElement'.
  Type 'null' is not assignable to type 'HTMLInputElement'.

Pass the element type as a generic and check for null before you use it. MDN's querySelector reference confirms the null return value.

const el = document.querySelector<HTMLInputElement>("#email");
if (el) el.value = "test@example.com";

The non-null assertion querySelector("#email")! also compiles. Use it only when the element is guaranteed by your own HTML, because if the selector is wrong you get a Cannot read properties of null TypeError at runtime instead.

6. Forgetting to await a Promise

An async function always returns a Promise, never the bare value:

async function getCount(): Promise<number> {
  return 42;
}

function show() {
  const count: number = getCount();
  console.log(count);
}

c06_promise.ts(6,9): error TS2322: Type 'Promise<number>' is not assignable to type 'number'.

Make the calling function async and await the call:

async function show() {
  const count: number = await getCount();
  return count;
}

Without the type annotation, count would quietly be a Promise and you would print Promise { 42 } instead of the number. My async/await tutorial walks through the patterns.

7. An array with mixed types

TypeScript infers the element type from everything in the array literal:

const mixed = ["a", 1, "b"];
const names: string[] = mixed;

c07_union_array.ts(2,7): error TS2322: Type '(string | number)[]' is not assignable to type 'string[]'.
  Type 'string | number' is not assignable to type 'string'.
    Type 'number' is not assignable to type 'string'.

This output shows a three-level chain. The bottom line, Type 'number' is not assignable to type 'string', is the real problem: there is a number in the array. Either fix the data, declare the array as (string | number)[] and handle both cases, or filter it with a type guard such as mixed.filter((x): x is string => typeof x === "string").

8. A readonly array passed to a function that expects a mutable one

as const makes an array readonly, and TypeScript will not let a function that might call push() receive it:

const COLORS = ["red", "green"] as const;

function paint(colors: string[]) {
  colors.push("blue");
}

paint(COLORS);

c08_readonly.ts(7,7): error TS4104: The type 'readonly ["red", "green"]' is 'readonly' and cannot be assigned to the mutable type 'string[]'.

Here the message has a different code, TS4104, but it is the same assignability rule. If the function does not need to change the array, change its parameter to readonly string[], which accepts both mutable and readonly arrays. If it does need to change it, pass a copy: paint([...COLORS]). The handbook's object types page covers readonly arrays and tuples.

9. React useState(null) without a type

This is the React version of the error, and it is everywhere in Next.js projects. useState(null) infers the state type as null, forever:

import { useState } from "react";

type User = { id: number; name: string };

export function useUser(data: User) {
  const [user, setUser] = useState(null);
  setUser(data);
  setUser({ id: 1, name: "Mahir" });
  return user;
}

c09_usestate.ts(7,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'SetStateAction<null>'.
  Type 'User' provides no match for the signature '(prevState: null): null'.
c09_usestate.ts(8,13): error TS2353: Object literal may only specify known properties, and 'id' does not exist in type '(prevState: null) => null'.

Notice that passing a variable gives TS2345, while passing an object literal gives TS2353. Both have the same cause. Tell useState what the state can hold, as the React useState reference shows for TypeScript:

import { useState } from "react";

type User = { id: number; name: string };

export function useUser() {
  const [user, setUser] = useState<User | null>(null);
  setUser({ id: 1, name: "Mahir" });
  return user;
}

That file compiled with exit code 0 against @types/react 19. The same fix applies to useState([]), which infers never[]; write useState<Item[]>([]).

10. Returning a concrete value from a generic function

This is the most confusing message of the ten:

function withDefault<T>(value: T | undefined): T {
  if (value === undefined) {
    return "default";
  }
  return value;
}

c10_generic.ts(3,5): error TS2322: Type 'string' is not assignable to type 'T'.
  'T' could be instantiated with an arbitrary type which could be unrelated to 'string'.

The function promises to return a T, and the caller chooses T. If someone calls withDefault<number>(undefined), returning "default" would break that promise. The generics handbook page covers this. The fix is to let the caller supply the fallback, so it is always a T:

function withDefault<T>(value: T | undefined, fallback: T): T {
  return value === undefined ? fallback : value;
}

The fixes in one file, compiled and run

I collected the fixes for causes 1, 2, 3, 5, 6, 8 and 10 into a single file, f01_fixes.ts, using exactly the snippets shown above, to prove they compile together under strict mode and behave correctly at runtime. The compiler result:

[exit 0]

Exit code 0 with no messages means no type errors. Compiling to JavaScript and running it in Node printed:

Hi Mahir 12 right 2 5
count 42

The DOM block is wrapped in a typeof document check only because this test ran in Node, which has no document.

Why "as" is the wrong first fix (and satisfies is better)

A type assertion tells TypeScript to trust you. It removes the error but not the bug:

interface Product { id: number; title: string; price: number }

// "as" silences the compiler, and the bug ships
const risky = { id: 1, title: "Mug" } as Product;
console.log(risky.price.toFixed(2));

[exit 0]

It compiled cleanly. Then Node crashed when the code ran, with the classic Cannot read properties of undefined error:

f03_as_vs_satisfies.js:4
console.log(risky.price.toFixed(2));
                        ^

TypeError: Cannot read properties of undefined (reading 'toFixed')
    at Object.<anonymous> (f03_as_vs_satisfies.js:4:25)

The satisfies operator, added in TypeScript 4.9, checks the object without changing its type, so the same mistake is caught before it ships:

interface Product { id: number; title: string; price: number }

const checked = { id: 1, title: "Mug" } satisfies Product;

f04_satisfies.ts(3,41): error TS2741: Property 'price' is missing in type '{ id: number; title: string; }' but required in type 'Product'.

My rule of thumb: as is fine for genuinely unknowable things, like parsed JSON you validate elsewhere. For anything you wrote yourself, prefer an annotation or satisfies. And any switches off checking for everything the value touches, so treat it as a last resort.

How to fix it fast: a checklist

Read the last indented line of the message. That is the exact part that does not fit.
If it mentions undefined or null, add a check, a default with ??, or fix the data source.
If it says string where a union like 'left' | 'right' is expected, use const, an annotation, as const or satisfies.
If it mentions Promise, add await.
If it mentions never or null inside React state, give useState a type argument.
If it mentions readonly, widen the parameter to readonly T[].
If it mentions a generic T, stop returning a fixed value from a generic function.
Only then consider as, and never use it to paper over undefined.

If you just upgraded to TypeScript 7 and the error count exploded, you can set "strict": false in tsconfig.json temporarily and then turn the individual strict checks back on one by one. For quick formatting and conversion jobs while you debug, my free browser tools work right in your browser.

Frequently asked questions

What does Type 'X' is not assignable to type 'Y' mean?

It means the value on the right might hold something that the type on the left does not allow. TypeScript checks every possible value of X, so even one member, like undefined, is enough to fail.

What is the difference between TS2322 and TS2345?

They are the same assignability check in different places. TS2322 is reported for assignments, declarations and return values. TS2345 is reported when you pass an argument to a function parameter.

How do I fix string | undefined is not assignable to type string?

Narrow the value first. Use a default with ??, an if check that returns early, or fix the source so the value is never missing. A non-null assertion with ! compiles too, but it only moves the risk to runtime.

Why did these errors appear after upgrading to TypeScript 7?

TypeScript 7.0 enables strict mode by default. In my test the same file failed on 7.0.2 with no flags and passed on 5.9.3 with default options. Set strict to false temporarily if you need time to migrate.

Is it OK to fix the error with as or any?

Only when you truly know more than the compiler, such as validated JSON. In my test an as Product assertion compiled cleanly and then crashed at runtime with Cannot read properties of undefined. satisfies caught the same mistake at compile time.

Why does useState(null) cause not assignable errors in React?

TypeScript infers the state type from the initial value, so useState(null) can only ever hold null. Write useState(null) so the setter accepts a User.

Last checked: 9 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

git fetch vs git pull (vs git pull --rebase): Differences, Divergent Branches and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:49:42 +0000

git fetch downloads new commits, branches and tags from a remote and updates your remote-tracking branches (like origin/main), but it never touches your local branch or your working files. git pull runs a fetch and then integrates the result into your current branch, by fast-forward, merge or rebase. Use git fetch when you want to look before you change anything, and git pull (ideally --ff-only or --rebase) when you are ready to update.

That one-line difference explains most "why did Git do that?" moments. The git pull documentation describes pull as a fetch followed by a merge or rebase, so every surprise from pull really comes from the second half.

To test all of this properly, I built a small setup on my machine: a bare repository acting as the remote, and clones called alice, bob and carol taking turns to push. Everything ran on Git 2.47.3 with an empty global config, so no personal settings changed the results. I fixed the commit dates, which keeps the hashes below identical every time the script runs. The remote path in the output is /tmp/gitdemo-nov08/origin.

In this guide:

What git fetch actually changes
Integrating after a fetch
What git pull does in one step
"fatal: Need to specify how to reconcile divergent branches"
git pull --ff-only: refuse anything but a fast-forward
git pull --rebase vs git pull --no-rebase
When pull says your local changes would be overwritten
git fetch --prune: clean up deleted remote branches
Previewing with --dry-run and FETCH_HEAD
git fetch vs git pull comparison table
Set sensible defaults once
Which should you use?
Frequently asked questions

What git fetch actually changes

Alice pushes a commit. Bob runs git fetch. Here is everything Bob sees:

$ git log --oneline -1 main
8c404c0 first commit

$ git fetch origin
From /tmp/gitdemo-nov08/origin
   8c404c0..cc18d13  main       -> origin/main

$ git status
On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

$ git log --oneline main..origin/main
cc18d13 alice: add v2

$ git diff --stat main origin/main
 app.txt | 1 +
 1 file changed, 1 insertion(+)

$ cat app.txt
v1

Read it top to bottom. The fetch line 8c404c0..cc18d13 main -> origin/main says only origin/main moved. Bob's main still points at 8c404c0, and app.txt still holds just v1. git status now knows Bob is one commit behind, because it compares main with the freshly updated origin/main.

This is why fetch is always safe. It cannot cause conflicts and it cannot lose work. The git fetch docs describe it as downloading objects and refs from another repository, and that is all it does. One practical tip: git status only reports "behind" accurately after a fetch. Without one, it compares against stale data.

Integrating after a fetch

Once Bob has looked at git log main..origin/main, he can integrate. The safest choice is a fast-forward-only merge, which refuses to create a merge commit:

$ git merge --ff-only origin/main
Updating 8c404c0..cc18d13
Fast-forward
 app.txt | 1 +
 1 file changed, 1 insertion(+)

$ cat app.txt
v1
v2 from alice

Fetch plus git merge --ff-only origin/main is exactly what git pull --ff-only does in one step. Splitting it in two just gives you a moment to review. You can also run git rebase origin/main instead of the merge if you have local commits, which leads to the same result as git pull --rebase. The git merge docs explain fast-forward in detail.

What git pull does in one step

Alice pushes again. This time Bob just runs git pull:

$ git pull
From /tmp/gitdemo-nov08/origin
   cc18d13..2d2db15  main       -> origin/main
Updating cc18d13..2d2db15
Fast-forward
 app.txt | 1 +
 1 file changed, 1 insertion(+)

$ git log --oneline -3
2d2db15 alice: add v3
cc18d13 alice: add v2
8c404c0 first commit

The first two lines are the fetch. The rest is the merge, and because Bob had no commits of his own, Git simply moved main forward. This is the happy path, and it is why many people never think about the difference. Trouble starts when both sides have new commits.

If git pull ever stops with fatal: refusing to merge unrelated histories, that is a different problem: the two branches share no common commit at all. I covered it in fatal: refusing to merge unrelated histories.

"fatal: Need to specify how to reconcile divergent branches"

Now Alice and Bob both commit. Alice pushes first, then Bob pulls with no pull.rebase or pull.ff setting:

$ git pull
From /tmp/gitdemo-nov08/origin
   2d2db15..3711840  main       -> origin/main
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

$ git status -sb
## main...origin/main [ahead 1, behind 1]

The fetch succeeded (note the 2d2db15..3711840 line), so origin/main is up to date. Only the integration step stopped, and nothing in Bob's branch or files changed. [ahead 1, behind 1] means each side has one commit the other lacks.

Current Git versions refuse to guess here, and the hint lists all three choices. You can pick one per command with --rebase, --no-rebase or --ff-only, or set a default with git config. The next three sections show each choice on real diverged branches.

git pull --ff-only: refuse anything but a fast-forward

With --ff-only, Git only updates your branch if it can do so without a merge or rebase. On diverged branches it stops:

$ git pull --ff-only
hint: Diverging branches can't be fast-forwarded, you need to either:
hint:
hint:   git merge --no-ff
hint:
hint: or:
hint:
hint:   git rebase
hint:
hint: Disable this message with "git config advice.diverging false"
fatal: Not possible to fast-forward, aborting.

That refusal is the point. On a shared main branch you usually never commit directly, so a fast-forward should always work. If it does not, something unexpected happened, and you want to stop and look rather than create a surprise merge commit.

git pull --rebase vs git pull --no-rebase

Bob decides to rebase. His commit gets replayed on top of Alice's:

$ git pull --rebase
Rebasing (1/1)
Successfully rebased and updated refs/heads/main.

$ git log --oneline --graph -4
* 17c931b bob: add bob.txt
* 3711840 alice: add alice.txt
* 2d2db15 alice: add v3
* cc18d13 alice: add v2

History stays in a straight line. Note that Bob's commit now has a new hash (17c931b), because rebase creates new commits. That is fine for work you have not pushed yet, and risky for commits other people already have.

For comparison, I set up a second clone, bob2, with the same kind of divergence and ran --no-rebase:

$ git pull --no-rebase
Merge made by the 'ort' strategy.
 alice.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 alice.txt

$ git log --oneline --graph -4
*   8f1d343 Merge branch 'main' of /tmp/gitdemo-nov08/origin
|\  
| * 3711840 alice: add alice.txt
* | 4973363 bob2: add bob2.txt
|/  
* 2d2db15 alice: add v3

Now there is a merge commit with two parents, and the graph shows the fork. Neither approach is wrong. Rebase gives a tidy log, merge keeps an exact record. I compared them side by side, plus squash, in git merge vs rebase vs squash.

When pull says your local changes would be overwritten

Uncommitted edits can block a pull too. Bob changed line 1 of config.txt without committing, while Alice pushed a change to line 10 of the same file:

$ git status --short
 M config.txt

$ git pull --ff-only
From /tmp/gitdemo-nov08/origin
   74986d9..2ebd87b  main       -> origin/main
error: Your local changes to the following files would be overwritten by merge:
    config.txt
Please commit your changes or stash them before you merge.
Aborting
Updating 74986d9..2ebd87b

$ git pull --ff-only --autostash
Updating 74986d9..2ebd87b
Created autostash: ee764a3
Fast-forward
 config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Applied autostash.

$ git status --short
 M config.txt

$ head -1 config.txt
setting 1 = bob (uncommitted)

$ tail -1 config.txt
setting 10 = alice

$ git stash list

The first pull fetched, then refused to touch the file. (The Updating line lands after the error in my log only because output went to a file, where Git buffers normal output but not errors. In a terminal it comes first.) Adding --autostash stashed Bob's edit, fast-forwarded, and put the edit back. Both changes are now in the file and the stash list is empty.

If both sides had edited the same lines, the autostash would have needed manual conflict resolution. You can do the same thing by hand with git stash, pull, then git stash pop. The difference between pop and apply matters there, and I explained it in git stash pop vs apply.

git fetch --prune: clean up deleted remote branches

Fetch adds new remote branches, but by default it never removes ones that were deleted on the server. Here a feature-x branch appears, gets deleted on the remote, and lingers locally until a prune:

$ git fetch

$ git branch -r
  origin/HEAD -> origin/main
  origin/main

$ git fetch --prune
From /tmp/gitdemo-nov08/origin
 - [deleted]         (none)     -> origin/feature-x

After the prune, git branch -r showed only origin/HEAD and origin/main. Stale remote-tracking branches are harmless but confusing, especially in tab completion. To remove the branch on the remote and locally in one go, see how to delete a Git branch locally and remotely.

Previewing with --dry-run and FETCH_HEAD

Two lesser-known fetch details are handy when you are nervous about a remote:

$ git fetch --dry-run
From /tmp/gitdemo-nov08/origin
   2ebd87b..d886bbb  main       -> origin/main

$ git fetch
From /tmp/gitdemo-nov08/origin
   2ebd87b..d886bbb  main       -> origin/main

$ cat .git/FETCH_HEAD
d886bbb1f19422983234d444b5e71eae083912ab        branch 'main' of /tmp/gitdemo-nov08/origin

$ git status -sb
## main...origin/main [ahead 1, behind 1]

--dry-run printed what would change without updating anything, and the real fetch then printed the same line. FETCH_HEAD records the last fetched tip, so git log FETCH_HEAD or git diff HEAD FETCH_HEAD works even when you fetched a URL with no remote-tracking branch. The Pro Git chapter on remote branches explains how these refs fit together.

git fetch vs git pull comparison table

Here is the whole comparison in one place, based on the runs above:

Command	Downloads new commits?	Changes your branch and files?	Diverged branches	Best for
`git fetch`	Yes	No. Only `origin/*` refs move	Nothing happens	Checking what changed before you integrate
`git pull` (no config)	Yes	Yes, if it can fast-forward	Stops with "Need to specify how to reconcile divergent branches"	Quick updates on a branch you never commit to
`git pull --ff-only`	Yes	Only by fast-forward	Stops with "Not possible to fast-forward"	Safe default for shared main branches
`git pull --rebase`	Yes	Yes, replays your commits on top	Linear history, rewrites your local commits	Feature work you have not pushed yet
`git pull --no-rebase`	Yes	Yes, creates a merge commit	Adds a "Merge branch..." commit	Teams that want every integration recorded

Set sensible defaults once

You do not have to type flags every time. Here I configured a fresh clone, carol, with diverged history, then ran a plain git pull and git fetch:

$ git config pull.rebase true

$ git config fetch.prune true

$ git status -sb
## main...origin/main [ahead 1, behind 1]

$ git pull
Rebasing (1/1)
Successfully rebased and updated refs/heads/main.

$ git log --oneline --graph -3
* 9e8d54f carol: add carol.txt
* d886bbb alice: add v6
* 2ebd87b alice: change setting 10

$ git fetch
From /tmp/gitdemo-nov08/origin
 - [deleted]         (none)     -> origin/temp-branch

$ git branch -r
  origin/HEAD -> origin/main
  origin/main

With pull.rebase true, the plain pull rebased instead of stopping. With fetch.prune true, a normal fetch removed the deleted temp-branch by itself. Add --global to apply either setting to every repository. If you would rather never rewrite anything automatically, use git config --global pull.ff only instead, and decide case by case.

Which should you use?

Starting your day or before a review: git fetch, then git log main..origin/main to see what is new.
Updating a shared main branch you never commit to: git pull --ff-only.
Updating a feature branch with unpushed commits: git pull --rebase.
Your team wants merges recorded: git pull --no-rebase.
You have uncommitted edits: commit them, or add --autostash.
Remote branches look out of date: git fetch --prune, or set fetch.prune true.

When a pull goes wrong, nothing is lost: git reflog shows where your branch was a moment ago. If you also need to undo a commit afterwards, see how to undo the last commit and keep your changes.

Frequently asked questions

What is the main difference between git fetch and git pull?

git fetch only downloads new commits and updates remote-tracking branches such as origin/main. git pull does that fetch and then merges or rebases the changes into your current branch and working files.

Is git fetch safe to run at any time?

Yes. Fetch never changes your local branches, your staged changes or your working files, so it cannot cause conflicts. In my tests the working file was unchanged after every fetch.

Why does git pull say "Need to specify how to reconcile divergent branches"?

Your branch and the remote branch both have new commits, and you have not told Git whether to merge, rebase or only fast-forward. Pass --rebase, --no-rebase or --ff-only, or set pull.rebase or pull.ff in git config.

Is git pull --rebase better than git pull?

It keeps history linear and avoids extra merge commits, which most people prefer for unpushed feature work. Avoid it when your local commits have already been pushed and shared, because rebase gives them new hashes.

Does git fetch update my local branch?

No. It updates origin/main, not main. Run git merge --ff-only origin/main or git rebase origin/main afterwards, or use git pull to do both steps at once.

How do I see what git pull will change before running it?

Run git fetch first, then git log main..origin/main for the new commits and git diff main origin/main for the changes. git fetch --dry-run shows which refs would update without changing anything.

Does git pull fetch all branches?

A plain git pull fetches from the remote configured for your current branch and normally updates all its remote-tracking branches, but it only integrates into the branch you have checked out. Use git fetch --all to fetch from every remote.

How do I undo a git pull?

Use git reflog to find where your branch pointed before the pull, then git reset --hard to that entry if you have no uncommitted work to keep. A pull with --ff-only never creates a merge, so there is less to undo.

Last checked: 8 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

UnboundLocalError: cannot access local variable where it is not associated with a value in Python: 10 Causes and Fixes (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:49:15 +0000

Python raises UnboundLocalError: cannot access local variable 'x' where it is not associated with a value when a function reads a name that Python has decided is local to that function, but the line that gives it a value has not run yet. Any assignment to a name anywhere inside a function (including +=, for, import, del and except ... as) makes that name local for the whole function. The usual fixes are to give the variable a value before any branch or loop, pass values in and return them, or declare global or nonlocal when you really mean an outer variable.

On Python 3.10 and older the same error reads UnboundLocalError: local variable 'x' referenced before assignment. It is the same problem with a friendlier message in newer versions. The Python docs list UnboundLocalError as a subclass of NameError, raised for a local variable that has no value bound to it yet.

The confusing part is that the variable often does exist, right at the top of the file. I hit it myself on my first visit counter. I reproduced every example below on Python 3.13.5, and I re-ran the first one on 3.10.22, 3.11.17, 3.14.8 and 3.15.0rc3 to compare the messages. Paths in the tracebacks point at my test scripts under /workspace/seo-posts-nov08/test/python/.

In this guide:

What the error looks like
Why Python thinks the variable is local
The 10 causes at a glance
1. Augmented assignment (+=) to a global
2. Reading a global, then assigning it later
3. A variable assigned only inside an if branch
4. Using a loop variable after an empty loop
5. A try block that failed before the assignment
6. A nested function updating an outer variable
7. Reading a name after del
8. An import later in the same function
9. Using an except ... as variable after the block
10. Shadowing a built-in like len
How to find the cause in under a minute
Frequently asked questions

What the error looks like

Here is the classic version: a module-level counter and a function that tries to bump it.

count = 0

def add_visit():
    count += 1
    return count

print(add_visit())

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c01_global_counter.py", line 7, in <module>
    print(add_visit())
          ~~~~~~~~~^^
  File "/workspace/seo-posts-nov08/test/python/c01_global_counter.py", line 4, in add_visit
    count += 1
    ^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

The carets point at count on the += line. Python 3.11.17, 3.14.8 and 3.15.0rc3 printed the same final message. Python 3.10.22 printed the older wording, UnboundLocalError: local variable 'count' referenced before assignment, without the caret lines. Same bug, same fixes.

Why Python thinks the variable is local

Python decides the scope of every name when it compiles a function, before any line runs. The rule from the execution model is simple: if a name is bound anywhere in a function body, it is local to that whole function, unless you declare it global or nonlocal. Position does not matter. An assignment on the last line still makes the name local on the first line.

So count += 1 means "read local count, add 1, store local count". The read happens first, the local has no value yet, and Python refuses to quietly fall back to the global with the same name. That refusal is a good thing. A silent fallback would make bugs far harder to spot.

You can watch the compiler's decision yourself. This script inspects the function before calling it:

total = 100

def report():
    print("total is", total)
    total = 0

print("UnboundLocalError is NameError subclass:", issubclass(UnboundLocalError, NameError))
print("local names in report:", report.__code__.co_varnames)

import symtable
src = open(__file__).read()
table = symtable.symtable(src, __file__, "exec")
fn = table.lookup("report").get_namespaces()[0]
sym = fn.lookup("total")
print("total is_local:", sym.is_local(), "is_global:", sym.is_global())

try:
    report()
except NameError as e:
    print("caught by except NameError:", type(e).__name__, "-", e)

UnboundLocalError is NameError subclass: True
local names in report: ('total',)
total is_local: True is_global: False
caught by except NameError: UnboundLocalError - cannot access local variable 'total' where it is not associated with a value

co_varnames and symtable both list total as local before the function runs. And because UnboundLocalError subclasses NameError, except NameError catches both.

The 10 causes at a glance

Every cause below comes back to the same rule: something assigns the name inside the function, and a read runs before that assignment. Use this table to jump to the one that matches your code.

#	Cause	What you see	Fix
1	`count += 1` on a global	Fails on the first call	Return a new value, or declare `global`
2	Read a global, assign it later in the same function	Fails on the read, not the assignment	Rename the local or use `global`
3	Assigned only inside an `if`	Works for some inputs only	Set a default before the `if`
4	Loop variable after an empty loop	Works until the list is empty	Initialise before the loop
5	`try` failed before the assignment	Error inside `except`/`finally`	Use `with` or set `None` first
6	Closure updates an outer variable	Inner function fails on `+=`	Declare `nonlocal`
7	`del x`, then read `x`	Fails after the delete	Do not reuse a deleted name
8	`import` later in the same function	Module name fails at the top of the function	Move the import to the top of the file
9	`except ... as err` used after the block	Fails after the handler ends	Copy `err` to another variable
10	Built-in name like `len` reassigned later	Built-in suddenly "missing"	Pick a different variable name

1. Augmented assignment (+=) to a global

This is the example from the top of the post, and it is the most common cause by far. Counters, running totals and "last seen" values all hit it. +=, -=, *= and friends all count as assignments, so the name becomes local.

The cleanest fix is to stop mutating the global at all: pass the value in and return the new one. If the function really must change module-level state, declare it with the global statement. Here are both, plus the fixes for causes 3, 4 and 6, from one test run:

# Fix 1: pass in and return instead of mutating a global
def add_visit(count):
    return count + 1

visits = 0
visits = add_visit(visits)
print("returned:", visits)

# Fix 2: global, when you really mean the module-level name
count = 0
def add_visit_global():
    global count
    count += 1
    return count
print("global:", add_visit_global(), add_visit_global())

# Fix 3: nonlocal for closures
def make_counter():
    n = 0
    def increment():
        nonlocal n
        n += 1
        return n
    return increment
c = make_counter()
print("nonlocal:", c(), c(), c())

# Fix 4: initialise before branches and loops
def label(score):
    result = "fail"
    if score >= 50:
        result = "pass"
    return result
print("label:", label(72), label(30))

def last_item(items, default=None):
    item = default
    for item in items:
        pass
    return item
print("last_item:", last_item(["a", "b"]), last_item([]))

returned: 1
global: 1 2
nonlocal: 1 2 3
label: pass fail
last_item: b None

I prefer the return-value version: it keeps functions easy to test.

2. Reading a global, then assigning it later

This one surprises people because the failing line is a plain read. The assignment that causes it sits further down:

total = 100

def report():
    print("total is", total)
    total = 0

report()

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c02_read_then_assign.py", line 7, in <module>
    report()
    ~~~~~~^^
  File "/workspace/seo-posts-nov08/test/python/c02_read_then_assign.py", line 4, in report
    print("total is", total)
                      ^^^^^
UnboundLocalError: cannot access local variable 'total' where it is not associated with a value

The traceback points at the print, not at total = 0. Whenever the caret lands on a harmless-looking read, scan the rest of the function for any assignment to the same name. Usually you meant a different variable, so rename the local (for example new_total = 0). If you really meant to reset the global, add global total as the first line of the function.

3. A variable assigned only inside an if branch

Here the function works for some inputs and crashes for others, which makes it easy to ship by accident:

def label(score):
    if score >= 50:
        result = "pass"
    return result

print(label(72))
print(label(30))

pass
Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c03_if_branch.py", line 7, in <module>
    print(label(30))
          ~~~~~^^^^
  File "/workspace/seo-posts-nov08/test/python/c03_if_branch.py", line 4, in label
    return result
           ^^^^^^
UnboundLocalError: cannot access local variable 'result' where it is not associated with a value

A score of 72 takes the if branch and returns "pass". A score of 30 skips the only assignment, so result never gets a value. The fix is to set a default before the branch (result = "fail") or add an else. The fixes run above prints label: pass fail.

A close cousin of this bug is a function that only returns inside an if. That one does not raise UnboundLocalError. It quietly returns None, and the crash shows up later as 'NoneType' object is not subscriptable.

4. Using a loop variable after an empty loop

A for loop assigns its target on every pass. If the iterable is empty, the loop body never runs and the name never gets a value:

def last_item(items):
    for item in items:
        pass
    return item

print(last_item(["a", "b"]))
print(last_item([]))

b
Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c04_empty_loop.py", line 7, in <module>
    print(last_item([]))
          ~~~~~~~~~^^^^
  File "/workspace/seo-posts-nov08/test/python/c04_empty_loop.py", line 4, in last_item
    return item
           ^^^^
UnboundLocalError: cannot access local variable 'item' where it is not associated with a value

Two items work fine. An empty list crashes. Give the name a value before the loop, as last_item(items, default=None) does in the fixes run, or skip the loop entirely and use items[-1] if items else None. Empty lists cause plenty of other crashes too. If you also index into them, see IndexError: list index out of range.

5. A try block that failed before the assignment

This is a nasty one, because the second error hides the first. open() fails, so f is never assigned, and then finally tries to close it:

def load(path):
    try:
        f = open(path)
        data = f.read()
    except FileNotFoundError:
        print("missing file:", path)
    finally:
        f.close()

load("does-not-exist.txt")

missing file: does-not-exist.txt
Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c05_try_except.py", line 10, in <module>
    load("does-not-exist.txt")
    ~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/workspace/seo-posts-nov08/test/python/c05_try_except.py", line 8, in load
    f.close()
    ^
UnboundLocalError: cannot access local variable 'f' where it is not associated with a value

The handler ran and printed its message, then f.close() blew up. For files, sockets and locks, a with block solves this completely: it only closes what actually opened. When you cannot use with, set the variable to None before the try and check it in finally. Here are the with version and the fixes for causes 9 and 10:

# Fix: with closes the file only if it opened
def load(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print("missing file:", path)
        return None
print("load:", load("does-not-exist.txt"))

# Fix: keep the exception in another name
def parse(value):
    last_error = None
    try:
        return int(value)
    except ValueError as err:
        last_error = err
    print("last error was:", repr(last_error))
parse("abc")

# Fix: rename instead of shadowing a builtin
def summary(words):
    print("count:", len(words))
    word_count = len(words)
    return word_count
print("summary:", summary(["hi", "there"]))

missing file: does-not-exist.txt
load: None
last error was: ValueError("invalid literal for int() with base 10: 'abc'")
count: 2
summary: 2

6. A nested function updating an outer variable

Closures follow the same rule. The inner function assigns count, so count is local to the inner function, even though the outer function already has one:

def make_counter():
    count = 0
    def increment():
        count += 1
        return count
    return increment

counter = make_counter()
print(counter())

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c06_nested.py", line 9, in <module>
    print(counter())
          ~~~~~~~^^
  File "/workspace/seo-posts-nov08/test/python/c06_nested.py", line 4, in increment
    count += 1
    ^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

The fix is nonlocal, which tells Python to bind the name in the nearest enclosing function scope. In the fixes run, the counter with nonlocal n printed nonlocal: 1 2 3. The official Python programming FAQ covers this exact case under "Why am I getting an UnboundLocalError when the variable has a value?".

global would be wrong here: it points at the module, not at make_counter.

7. Reading a name after del

del unbinds a name. Inside a function, the name stays local, so reading it afterwards raises the same error:

def clean():
    temp = [1, 2, 3]
    del temp
    return len(temp)

clean()

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c07_del.py", line 6, in <module>
    clean()
    ~~~~~^^
  File "/workspace/seo-posts-nov08/test/python/c07_del.py", line 4, in clean
    return len(temp)
               ^^^^
UnboundLocalError: cannot access local variable 'temp' where it is not associated with a value

This usually appears after a refactor adds a del above an older use. Move the del after the last use, or drop it; locals are freed when the function returns anyway.

8. An import later in the same function

import json is an assignment too: it binds the name json. Put one inside a function, even in a branch that never runs, and the module-level import stops working for that whole function:

import json

def save(data):
    text = json.dumps(data)
    if not text:
        import json
    return text

print(save({"a": 1}))

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c08_late_import.py", line 9, in <module>
    print(save({"a": 1}))
          ~~~~^^^^^^^^^^
  File "/workspace/seo-posts-nov08/test/python/c08_late_import.py", line 4, in save
    text = json.dumps(data)
           ^^^^
UnboundLocalError: cannot access local variable 'json' where it is not associated with a value

The same thing happens with from x import y and with any name that matches a module you imported at the top. Keep imports at the top of the file, or put a lazy import at the very start of the function.

9. Using an except ... as variable after the block

Python deletes the name bound by except ... as err when the handler finishes. The compound statements reference explains why: it breaks a reference cycle between the exception and the stack frame. Inside a function, reading err afterwards fails:

def parse(value):
    try:
        return int(value)
    except ValueError as err:
        print("bad value:", value)
    print("last error was:", err)

parse("abc")

bad value: abc
Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c09_except_as.py", line 8, in <module>
    parse("abc")
    ~~~~~^^^^^^^
  File "/workspace/seo-posts-nov08/test/python/c09_except_as.py", line 6, in parse
    print("last error was:", err)
                             ^^^
UnboundLocalError: cannot access local variable 'err' where it is not associated with a value

At module level the same code raises NameError instead. Either way, copy the exception to another variable inside the handler (last_error = err), as the fixes run above shows. It printed last error was: ValueError("invalid literal for int() with base 10: 'abc'").

10. Shadowing a built-in like len

Built-ins follow the rule as well. Assign to len, list, id, type or sum anywhere in a function, and every earlier use of that built-in in the function breaks:

def summary(words):
    print("count:", len(words))
    len = 3
    return len

summary(["hi", "there"])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov08/test/python/c10_shadow_builtin.py", line 6, in <module>
    summary(["hi", "there"])
    ~~~~~~~^^^^^^^^^^^^^^^^^
  File "/workspace/seo-posts-nov08/test/python/c10_shadow_builtin.py", line 2, in summary
    print("count:", len(words))
                    ^^^
UnboundLocalError: cannot access local variable 'len' where it is not associated with a value

The error says "local variable 'len'", which looks bizarre until you spot the assignment two lines down. Rename the variable (word_count) and the built-in works again. If you are cleaning up text or JSON while you debug, my free browser tools run entirely on your device. Pylint (redefined-builtin) and Ruff with its flake8-builtins rules flag shadowed built-ins before you run the code.

How to find the cause in under a minute

Read the last line of the traceback and note the variable name.
Search the whole function for that name followed by =, +=, for, import, del, as or a walrus :=.
If the assignment is meant to change an outer variable, add global (module) or nonlocal (enclosing function).
If it is a different value with the same name, rename it.
If it only happens on some inputs, look for an if, loop or try that can skip the assignment, and give the variable a default first.
Still stuck? Print your_function.__code__.co_varnames, or use the symtable module as in the diagnosis script above.

Frequently asked questions

What does UnboundLocalError: cannot access local variable mean?

Python decided at compile time that the name is local to the function, because something in the function assigns to it. Then a line read the name before that assignment had run, so the local had no value.

Is it the same as local variable referenced before assignment?

Yes. Python 3.10 and older print local variable 'x' referenced before assignment. Python 3.11 and newer print cannot access local variable 'x' where it is not associated with a value. In my tests the cause and fixes were identical.

Why does the error happen when the variable is defined at the top of the file?

Any assignment to the same name inside the function, including +=, makes it a separate local variable for the whole function. The module-level variable is ignored until you declare it with global.

Should I just use global to fix it?

Use global only when the function genuinely must change module-level state. In most code it is cleaner to pass the value in as an argument and return the new value.

What is the difference between global and nonlocal?

global binds the name at module level. nonlocal binds it in the nearest enclosing function, which is what you need for counters inside closures and decorators.

Is UnboundLocalError a subclass of NameError?

Yes. issubclass(UnboundLocalError, NameError) returned True in my test, so except NameError catches both. Fixing the scope is still better than catching the error.

Last checked: 8 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

null vs undefined in JavaScript: Differences, Checks and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:48:48 +0000

undefined means a value was never assigned (missing property, missing argument, bare return). null is an intentional empty value you assign yourself. Prefer === when you care which one you have, use == null when either should count as empty, and reach for ?? / optional chaining when you want defaults without treating 0 or '' as missing.

MDN documents both primitives: null is the intentional absence of an object value, while undefined is the primitive for an uninitialized value. This guide shows the behaviour with real output from Node.js 24.22.1 running test/js/demo.mjs on this box. If loose vs strict equality still feels fuzzy, the null == undefined case below is one of the classic places where == and === disagree.

I also checked the same snippets mentally against everyday DOM and fetch patterns: document.getElementById returns null on a miss, optional JSON fields come back as undefined when absent, and many REST APIs send explicit null for cleared fields. Keeping those three stories straight saves a surprising number of production bugs.

In this guide:

At a glance: null vs undefined
typeof null is "object" (yes, really)
== vs === between null and undefined
Missing properties vs explicit null
Default parameters: undefined triggers, null does not
Optional chaining (?.) safely reads nested values
Nullish coalescing (??) vs logical OR (||)
JSON.stringify and JSON.parse quirks
Function returns, void 0, and ReferenceError
DOM, APIs and everyday pitfalls
Practical checks and when to use each
Frequently asked questions

At a glance: null vs undefined

Question	`null`	`undefined`
What it means	Intentional empty	Not assigned / missing
`typeof`	`"object"` (historical quirk)	`"undefined"`
`null == undefined`	`true`
`null === undefined`	`false`
Default params trigger?	No	Yes
`??` treats as missing?	Yes	Yes
`		` treats as missing?
JSON	Serialized as `null`	Keys omitted / array holes become `null`
Typical source	You assigned it; APIs; DOM	Missing props, no `return`, sparse arrays

Rule of thumb I use in application code: assign null when I want to say "I looked, there is nothing." Leave a property undefined (or omit it) when it was never set. Check with === null / === undefined when the difference matters, and with == null when either empty state should take the same branch.

typeof null is "object" (yes, really)

The first surprise every JavaScript developer hits:

console.log("typeof null:", typeof null);
console.log("typeof undefined:", typeof undefined);

typeof null: object
typeof undefined: undefined

typeof null === "object" is a decades-old language quirk. It does not mean null is a real object you can read properties from. Accessing a property on null or undefined throws - the crash covered in Cannot read properties of undefined.

Use typeof to detect undefined. Detect null with value === null, not with typeof.

== vs === between null and undefined

Loose equality treats them as matching. Strict equality does not:

console.log("null == undefined:", null == undefined);
console.log("null === undefined:", null === undefined);
console.log("null == null:", null == null);
console.log("undefined == undefined:", undefined == undefined);
console.log("null == 0:", null == 0);
console.log("undefined == 0:", undefined == 0);
console.log("null == false:", null == false);
console.log("undefined == false:", undefined == false);
console.log("Boolean(null):", Boolean(null));
console.log("Boolean(undefined):", Boolean(undefined));
console.log("!null:", !null, "!undefined:", !undefined);

null == undefined: true
null === undefined: false
null == null: true
undefined == undefined: true
null == 0: false
undefined == 0: false
null == false: false
undefined == false: false
Boolean(null): false
Boolean(undefined): false
!null: true !undefined: true

Both are falsy, so if (!value) collapses them with 0, '' and false. That is often too aggressive. The idiom if (value == null) catches only null and undefined - useful when zero should still count as a real value. For a deeper look at loose vs strict equality, see == vs === in JavaScript.

Missing properties vs explicit null

A property you never set is undefined. A property you set to null is present and empty:

const user = { name: "Ana" };
const userNull = { name: "Ana", email: null };
console.log("'email' in user:", "email" in user);
console.log("user.email:", user.email);
console.log("'email' in userNull:", "email" in userNull);
console.log("userNull.email:", userNull.email);
console.log("user.email === undefined:", user.email === undefined);
console.log("userNull.email === null:", userNull.email === null);

'email' in user: false
user.email: undefined
'email' in userNull: true
userNull.email: null
user.email === undefined: true
userNull.email === null: true

APIs often use null to mean "field exists but is empty" (no email on file) and omit the key - or leave it undefined after JSON.parse of a missing field - to mean "not provided". Pick one convention in your own code and stick to it. Object keys with an undefined value still show up in Object.keys if you assigned them explicitly:

const mixed = { a: null, b: undefined, c: 1 };
console.log("Object.keys(mixed):", Object.keys(mixed));
console.log("Object.values(mixed):", Object.values(mixed));
console.log("Object.entries(mixed):", Object.entries(mixed));

Object.keys(mixed): [ 'a', 'b', 'c' ]
Object.values(mixed): [ null, undefined, 1 ]
Object.entries(mixed): [ [ 'a', null ], [ 'b', undefined ], [ 'c', 1 ] ]

Default parameters: undefined triggers, null does not

This is one of the most practical differences in day-to-day functions:

function greet(name = "guest") {
  return "hi " + name;
}
console.log("greet():", greet());
console.log("greet(undefined):", greet(undefined));
console.log("greet(null):", greet(null));
console.log("greet('Ada'):", greet("Ada"));

greet(): hi guest
greet(undefined): hi guest
greet(null): hi null
greet('Ada'): hi Ada

Omitting the argument or passing undefined applies the default. Passing null does not - you get the string "null" after concatenation. If callers might send null from an API, normalize at the edge: name = name ?? "guest" inside the body, or reject null explicitly. Variables declared with let/const without an initializer are undefined until assigned; see var vs let vs const for the scoping side of that story.

Optional chaining (?.) safely reads nested values

Optional chaining short-circuits to undefined when it hits null or undefined, instead of throwing:

const payload = { user: { id: 7 } };
console.log("payload.user?.profile?.avatar:", payload.user?.profile?.avatar);
console.log("payload.missing?.x:", payload.missing?.x);
const maybeNull = null;
console.log("maybeNull?.length:", maybeNull?.length);

payload.user?.profile?.avatar: undefined
payload.missing?.x: undefined
maybeNull?.length: undefined

That return value is always undefined on a miss - never null - even if an intermediate was null. MDN's page on optional chaining covers ?.() and ?.[] forms too. Pair it with ?? when you want a default after a safe read.

Nullish coalescing (??) vs logical OR (||)

?? only falls through for null and undefined. || falls through for every falsy value:

console.log("null ?? 'fallback':", null ?? "fallback");
console.log("undefined ?? 'fallback':", undefined ?? "fallback");
console.log("0 ?? 'fallback':", 0 ?? "fallback");
console.log("'' ?? 'fallback':", "" ?? "fallback");
console.log("false ?? 'fallback':", false ?? "fallback");
console.log("null || 'or':", null || "or");
console.log("0 || 'or':", 0 || "or");

null ?? 'fallback': fallback
undefined ?? 'fallback': fallback
0 ?? 'fallback': 0
'' ?? 'fallback': 
false ?? 'fallback': false
null || 'or': or
0 || 'or': or

Use ?? when 0, '' or false are valid data. Use || only when any falsy value should become the default. MDN documents the operator under nullish coalescing.

JSON.stringify and JSON.parse quirks

JSON has null but no undefined. Serialization reflects that:

console.log("JSON.stringify({a:null,b:undefined}):", JSON.stringify({ a: null, b: undefined }));
console.log("JSON.stringify([null, undefined]):", JSON.stringify([null, undefined]));
console.log("JSON.parse('{\"a\":null}'):", JSON.parse('{"a":null}'));
console.log("JSON.parse('{}').b:", JSON.parse("{}").b);

JSON.stringify({a:null,b:undefined}): {"a":null}
JSON.stringify([null, undefined]): [null,null]
JSON.parse('{"a":null}'): { a: null }
JSON.parse('{}').b: undefined

Object keys whose value is undefined are dropped. Array holes / undefined slots become null in the JSON text. After JSON.parse, a missing key reads back as undefined, while an explicit JSON null stays null. MDN's JSON.stringify page covers replacer behaviour if you need custom handling.

Function returns, void 0, and ReferenceError

A function with no return yields undefined. Returning null is a deliberate choice:

function noReturn() {}
function returnNull() { return null; }
function returnUndef() { return undefined; }
console.log("noReturn():", noReturn());
console.log("returnNull():", returnNull());
console.log("returnUndef():", returnUndef());
console.log("void 0 === undefined:", void 0 === undefined);
let x;
console.log("let x; x === undefined:", x === undefined);

noReturn(): undefined
returnNull(): null
returnUndef(): undefined
void 0 === undefined: true
let x; x === undefined: true

Reading a variable that was never declared is a ReferenceError, not undefined - except with typeof, which safely returns "undefined":

try {
  console.log(notDeclaredAtAll);
} catch (e) {
  console.log("caught:", e.name + ": " + e.message);
}
console.log("typeof notDeclaredAtAll:", typeof notDeclaredAtAll);

caught: ReferenceError: notDeclaredAtAll is not defined
typeof notDeclaredAtAll: undefined

Sparse arrays also produce undefined reads for empty slots, but in says the index is missing:

const arr = [1, , 3];
console.log("arr.length:", arr.length);
console.log("arr[1]:", arr[1]);
console.log("1 in arr:", 1 in arr);
console.log("arr.map(x => x):", arr.map(x => x));

arr.length: 3
arr[1]: undefined
1 in arr: false
arr.map(x => x): [ 1, <1 empty item>, 3 ]

DOM, APIs and everyday pitfalls

Three places this distinction shows up constantly:

DOM lookups - document.getElementById('missing') returns null. Reading .value on that result throws. Guard with if (el == null) before you touch properties.
Fetch / JSON APIs - a missing JSON key becomes undefined after JSON.parse. An explicit "email": null stays null. Do not treat them the same if your UI has different copy for "unknown" vs "cleared".
Function options objects - fn({ timeout: undefined }) still has the key; defaults written as options.timeout ?? 3000 will replace it, which is usually what you want. Passing timeout: null also triggers ??, so document whether null means "no timeout" or "use default".

Optional chaining helps for deep reads, but remember a miss always yields undefined, even when the chain hit a null. If you need to preserve an explicit null from an API as null in your UI state, assign it deliberately after the read instead of relying on ?. alone.

Array holes are another footgun: sparse slots read as undefined, yet in says the index is missing, and map skips the callback for empty slots. Prefer dense arrays (filter, flat, or explicit undefined fills) when you care about every index.

Practical checks and when to use each

Helpers I keep nearby:

function isNullish(v) { return v == null; } // catches null and undefined
function isNull(v) { return v === null; }
function isUndef(v) { return typeof v === "undefined"; }
console.log("isNullish(null):", isNullish(null));
console.log("isNullish(undefined):", isNullish(undefined));
console.log("isNullish(0):", isNullish(0));
console.log("isNull(null):", isNull(null));
console.log("isUndef(undefined):", isUndef(undefined));
console.log("isUndef(null):", isUndef(null));

isNullish(null): true
isNullish(undefined): true
isNullish(0): false
isNull(null): true
isUndef(undefined): true
isUndef(null): false

Use undefined for "not set yet": missing optional args, uninitialized locals, absent object keys.
Use null for "set, but empty": cleared form fields, API "no value", DOM nodes that do not exist (document.getElementById returns null).
Check with === when the difference matters; == null when either empty state is fine.
Prefer ?? over || for defaults when zero/empty-string are valid.
Prefer ?. over manual null checks for deep reads.

If you call something that is not a function while handling these values, you will see a different error - covered in TypeError: X is not a function.

Quick decision tree I use when reviewing a PR:

Is the empty state intentional and persistent? Prefer null.
Is the value simply not provided yet? Prefer leaving it undefined / omitted.
Do I need a default without wiping 0 or ''? Use ??, not ||.
Am I reading a deep path that might be missing? Use ?., then ?? for the default.
Am I comparing to empty? Prefer == null for either, or === when the exact flavour matters.

All snippets above were run on Node.js 24.22.1 via test/js/demo.mjs. The same results hold in current Chromium and Firefox for the language-level bits (typeof, ??, ?., JSON.stringify). DOM return values are browser APIs, not Node, but the null convention is the same in the HTML Standard.

Frequently asked questions

What is the difference between null and undefined in JavaScript?

undefined means a value was never assigned (missing property, missing argument, no return). null is an intentional empty value you assign. They compare equal with == and unequal with ===.

Why is typeof null equal to "object"?

It is a long-standing language quirk. null is still a primitive, not a real object. Detect it with value === null, not with typeof.

When should I use == null?

When either null or undefined should take the same branch. value == null is true only for those two; it leaves 0, '' and false alone.

Do default parameters work with null?

No. Defaults apply when the argument is missing or undefined. Passing null uses null as the value.

What does ?? do that || does not?

?? falls back only for null and undefined. || falls back for every falsy value, including 0, '' and false.

How does JSON treat null and undefined?

JSON has null but not undefined. JSON.stringify drops object keys whose value is undefined, and turns undefined array slots into null. JSON.parse of a missing key yields undefined when you read it.

Is a missing object property null or undefined?

Reading a missing property returns undefined. The key is not in the object. An explicit null means the key exists and was set empty.

What does document.getElementById return when nothing matches?

It returns null, not undefined. That is a common DOM example of intentional emptiness, so check with === null or == null before you read properties.

Last checked: 7 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

IndexError: list index out of range in Python: 10 Causes and Fixes (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:48:21 +0000

Python raises IndexError: list index out of range when you index a sequence (usually a list) at a position that does not exist. Valid indexes for a list of length n are 0 through n-1 (and -1 through -n). The quickest fixes are a len check before you index, a narrow try/except IndexError, safer loops with enumerate, and never hard-coding a length you already changed with pop, remove or split.

The Python docs list IndexError as the exception raised when a sequence subscript is out of range. That is the whole story. The hard part is working out why the index is wrong: the list was empty, you used len as an index (off-by-one), a split returned fewer fields than you expected, or you shrank the list while still walking the old length.

I reproduced every example below on Python 3.13.5, and I re-ran the empty-list traceback on 3.11.17 and 3.14.8. All three printed the same message and caret underlining. Paths in the tracebacks point at my test scripts under /workspace/seo-posts-nov07/test/python/.

In this guide:

What IndexError looks like
The 10 causes at a glance
1. Indexing an empty list
2. Off-by-one: using len(lst) as an index
3. Length changed after pop or delete
4. split() or CSV rows shorter than you expected
5. Negative indexes past -len(lst)
6. Mutating a list while walking a fixed length
7. Nested lists: the crash is often the inner index
8. Strings raise a closely related IndexError
9. range() that starts at 1 (or ends past len)
10. Slicing is forgiving; indexing is not
Reliable fixes checklist
Frequently asked questions

What IndexError looks like

Here is the smallest crash. The list is empty, so there is no index 0:

nums = []
print(nums[0])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c01_empty.py", line 2, in <module>
    print(nums[0])
          ~~~~^^^
IndexError: list index out of range

Since Python 3.11, the traceback underlines the lookup. The tildes sit under nums and the carets under [0], so you know which expression failed. The same traceback printed on 3.11.17 and 3.14.8.

If the variable was None instead of a list, you would see a different exception: TypeError: 'NoneType' object is not subscriptable. That family of crashes is covered in TypeError: NoneType is not subscriptable.

The 10 causes at a glance

#	Cause	How to spot it	Fix
1	Empty list	`IndexError` on `[0]`	Check `if lst:` / `len`
2	Off-by-one (`lst[len(lst)]`)	Index equals length	Use `0..len-1` or `[-1]`
3	Length changed after `pop`	Worked before a delete	Re-check length; use `deque`
4	Short `split` / CSV row	Fewer parts than expected	Pad or guard `len(parts)`
5	Negative index beyond `-len`	`lst[-n-1]`	Bound-check negatives too
6	Mutating while indexing a fixed range	Crash mid-loop after `pop`	Iterate a copy / reverse
7	Unpacking short rows by index	Crash on `row[2]`	Pad fields; validate rows
8	String index out of range	Message says `string`	Same rules; check `len`
9	Nested list, wrong level	Carets under inner `[]`	Print each level; check lengths
10	`range` / slice vs index mix-up	Slice works, `[i]` crashes	Remember slices are forgiving

1. Indexing an empty list

An empty list has length 0. There is no valid positive or negative index. nums[0] and nums[-1] both raise.

Fix: test emptiness first, or catch narrowly when absence is exceptional:

items = ["a", "b"]
idx = 5
if 0 <= idx < len(items):
    print(items[idx])
else:
    print("out of range: idx", idx, "len", len(items))

try:
    print(items[5])
except IndexError as e:
    print("caught:", repr(e))

it = iter(items)
print("first:", next(it, None))
print("second:", next(it, None))
print("third:", next(it, None))

out of range: idx 5 len 2
caught: IndexError('list index out of range')
first: a
second: b
third: None

next(iterator, default) is a clean way to pull the first item without indexing. For optional "first element" reads, prefer that or an explicit if items: guard over a bare items[0].

2. Off-by-one: using len(lst) as an index

A list of three items has indexes 0, 1 and 2. Index 3 is one past the end - the classic off-by-one:

items = ["a", "b", "c"]  # len 3, valid indexes 0..2
print("len:", len(items))
print(items[3])

len: 3
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c02_off_by_one.py", line 3, in <module>
    print(items[3])
          ~~~~~^^^
IndexError: list index out of range

Fix: the last item is items[-1] or items[len(items) - 1], never items[len(items)]. When you loop with indexes, use range(len(items)) (which stops before len) or, better, enumerate. Sequence indexing rules live in the Python built-in types docs.

3. Length changed after pop or delete

You computed an index when the list was longer. After pop, that index is gone:

queue = ["one", "two", "three"]
print("before pop:", queue, "len", len(queue))
queue.pop()
print("after pop:", queue, "len", len(queue))
print(queue[2])

before pop: ['one', 'two', 'three'] len 3
after pop: ['one', 'two'] len 2
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c03_after_pop.py", line 5, in <module>
    print(queue[2])
          ~~~~~^^^
IndexError: list index out of range

Fix: re-check len after every mutation, or use a structure that matches the access pattern. For queues, collections.deque gives cheap left pops without leaving stale indexes around:

from collections import deque
q = deque(["one", "two", "three"])
print("popleft:", q.popleft())
print("remaining:", list(q))

popleft: one
remaining: ['two', 'three']

Lists, tuples, sets and dicts each behave differently under indexing and membership; if you are choosing a structure, see list vs tuple vs set vs dict.

4. split() or CSV rows shorter than you expected

str.split returns only the parts that exist. A line with two fields is length 2, so index 2 raises:

line = "Alice,admin"
parts = line.split(",")
print("parts:", parts, "len", len(parts))
print(parts[2])  # expected email at index 2

parts: ['Alice', 'admin'] len 2
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c04_split_short.py", line 4, in <module>
    print(parts[2])  # expected email at index 2
          ~~~~~^^^
IndexError: list index out of range

The same pattern shows up when you pull fields by index from a short CSV row:

row = "id,name".split(",")  # only 2 fields; expected 3
print("row:", row)
uid, name, email = row[0], row[1], row[2]

row: ['id', 'name']
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c07_csv_row.py", line 4, in <module>
    uid, name, email = row[0], row[1], row[2]
                                       ~~~^^^
IndexError: list index out of range

Fix: pad missing fields, or refuse the row early:

line = "Alice,admin"
parts = line.split(",")
if len(parts) < 3:
    parts = parts + [""] * (3 - len(parts))
name, role, email = parts[0], parts[1], parts[2]
print("name:", name, "role:", role, "email:", repr(email))

first, *rest = "a,b".split(",")
print("first:", first, "rest:", rest)

name: Alice role: admin email: ''
first: a rest: ['b']

5. Negative indexes past -len(lst)

Negative indexes count from the end. -1 is the last item, -len(lst) is the first. One step further raises:

letters = ["x", "y", "z"]
print("letters[-1]:", letters[-1])
print("letters[-3]:", letters[-3])
print(letters[-4])

letters[-1]: z
letters[-3]: x
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c05_negative.py", line 4, in <module>
    print(letters[-4])
          ~~~~~~~^^^^
IndexError: list index out of range

Fix: bound-check negatives the same way you check positives:

letters = ["x", "y", "z"]
n = -4
if -len(letters) <= n < len(letters):
    print(letters[n])
else:
    print("negative index out of range:", n)

def at(seq, i, default=None):
    try:
        return seq[i]
    except IndexError:
        return default

print("at(letters, 99):", at(letters, 99))
print("at(letters, -1):", at(letters, -1))

negative index out of range: -4
at(letters, 99): None
at(letters, -1): z

A tiny at() helper keeps call sites clean when a missing position should become a default instead of a crash. For missing keys on dicts you want a different exception and fix path - see KeyError in Python.

6. Mutating a list while walking a fixed length

Hard-coding the old length (or caching len once) and then pop-ing inside the loop is a reliable way to walk off the end:

nums = [10, 20, 30, 40]
i = 0
while i < 4:  # hard-coded old length
    print("i", i, "value", nums[i])
    if nums[i] % 20 == 0:
        nums.pop(i)
    else:
        i += 1

i 0 value 10
i 1 value 20
i 1 value 30
i 2 value 40
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c06_mutate_while_iter.py", line 5, in <module>
    print("i", i, "value", nums[i])
                           ~~~~^^^
IndexError: list index out of range

After popping 20, the list is shorter, but the loop still aims for index 3. Fix: iterate indexes in reverse when deleting, or build a new list:

nums = [10, 20, 30, 40]
for i in range(len(nums) - 1, -1, -1):
    if nums[i] % 20 == 0:
        nums.pop(i)
print("after reverse pop:", nums)

items = ["red", "green", "blue"]
for i, value in enumerate(items):
    print(i, value)

after reverse pop: [10, 30]
0 red
1 green
2 blue

7. Nested lists: the crash is often the inner index

Chained indexes fail at the first bad level. The caret underline tells you which [] broke:

matrix = [[1, 2], [3, 4]]
print("matrix[0]:", matrix[0])
print(matrix[1][2])

matrix[0]: [1, 2]
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c09_nested.py", line 4, in <module>
    print(matrix[1][2])
          ~~~~~~~~~^^^
IndexError: list index out of range

matrix[1] exists ([3, 4]), but that inner list only has indexes 0 and 1. Fix: print each level, check len(matrix[r]) before matrix[r][c], and treat ragged rows as data you must validate. When you are pasting sample matrices while debugging, the helpers on mfaysal.com/free-tools are handy for a quick look.

8. Strings raise a closely related IndexError

Strings are sequences too. Index past the end and you get a sibling message:

word = "hi"
print("len:", len(word))
print(word[2])

len: 2
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c08_str_index.py", line 4, in <module>
    print(word[2])
          ~~~~^^^
IndexError: string index out of range

Same rules: valid indexes are 0..len-1. Slicing a string is forgiving (word[10:20] returns ''); indexing is not. Prefer slicing when you want a tolerant read, and indexing when a missing character should be an error.

9. range() that starts at 1 (or ends past len)

People sometimes write range(1, len(names) + 1) because they want "human" numbering, then use i as an index:

names = ["Ada", "Lin"]
for i in range(1, len(names) + 1):
    print(i, names[i])

1 Lin
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c10_range_vs_len.py", line 4, in <module>
    print(i, names[i])
             ~~~~~^^^
IndexError: list index out of range

Index 1 printed Lin; index 2 does not exist. Fix: keep display numbers separate from indexes:

names = ["Ada", "Lin"]
for i, name in enumerate(names, start=1):
    print(i, name)  # i is 1-based for display

Or loop with range(len(names)) and add 1 only when you print. Mixing 1-based counting with 0-based indexing is one of the most common IndexError sources in beginner code and in quick scripts.

10. Slicing is forgiving; indexing is not

Slices clamp to the ends of the sequence. A single index does not:

data = [1, 2, 3]
print("slice data[5:]:", data[5:])
print("slice data[1:10]:", data[1:10])
print(data[5])

slice data[5:]: []
slice data[1:10]: [2, 3]
Traceback (most recent call last):
  File "/workspace/seo-posts-nov07/test/python/c11_slice_vs_index.py", line 5, in <module>
    print(data[5])
          ~~~~^^^
IndexError: list index out of range

That difference surprises people who "tested" with a slice in the REPL and then shipped a bare index. Fix: know which one you mean. Use a slice when an empty result is fine. Use an index (and a guard) when a missing position is a real error. The data structures tutorial covers list operations in the official Python tutorial.

Reliable fixes checklist

Read the caret line: which index expression failed?
Print len(seq) and the index you asked for.
Prefer enumerate over hand-rolled range(len(...)) when you need both index and value.
After pop/remove/split, re-check length before indexing.
Pad or reject short CSV / split rows instead of assuming field counts.
Use reverse iteration (or a new list) when deleting by index.
Remember: slices forgive, indexes do not.
Catch IndexError narrowly at boundaries; do not swallow Exception.

deque, used earlier for queue-style pops, lives in the collections module. Reach for it when you need cheap left-side operations; keep a plain list when random access by index is the main job.

Frequently asked questions

What does IndexError: list index out of range mean?

It means you used square brackets to read a position that does not exist on a list (or another sequence). For a list of length n, valid indexes are 0 through n-1 and -1 through -n.

Why does my loop raise IndexError after a few iterations?

Usually the list shrank (pop/remove) while the loop still used the old length, or you started range at 1 and used those numbers as indexes. Print len and the index each time the body runs.

How do I safely get the first or last item?

Check if the list is non-empty, then use lst[0] or lst[-1]. Alternatively use next(iter(lst), default) for the first item without indexing.

Why does a slice work but lst[i] crash?

Slices clamp to the sequence bounds and can return []. A single index must be in range or Python raises IndexError.

Is IndexError the same as string index out of range?

Same exception class, different message. Strings, lists, tuples and other sequences all raise IndexError when a subscript is out of range.

Should I catch IndexError or check len first?

If missing indexes are normal, check len or use a helper with a default. If they should never happen at that layer, let IndexError propagate or catch it narrowly at a boundary.

How is IndexError different from KeyError?

IndexError is for out-of-range sequence positions. KeyError is for missing keys on mappings (dicts). They look similar in a traceback but the fixes differ.

Does enumerate prevent IndexError?

It prevents the common off-by-one from hand-rolled ranges, because it only yields real indexes. It will not save you if you later index with a different, invalid number.

Last checked: 7 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

Promise.all vs Promise.allSettled vs Promise.race in JavaScript: Differences and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:47:54 +0000

Promise.all waits for every promise to fulfill and fails fast on the first rejection. Promise.allSettled waits for every promise to finish and always fulfills with an array of {status, value|reason} results. Promise.race settles with whichever promise settles first, success or failure. Use all when one failure should cancel the whole batch, allSettled when you need every outcome, and race for timeouts or "first response wins".

MDN's pages for these methods are the official reference. This guide shows the behaviour with real timings I measured on Node.js 24.22.1 (and confirmed the methods exist on Node 20.20.2 and 18.20.8). If async/await itself is still fuzzy, start with my async/await tutorial, then come back here for the combinators.

Helper used in every timing test:

function delay(ms, value, shouldReject = false) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (shouldReject) reject(new Error(String(value)));
      else resolve(value);
    }, ms);
  });
}

In this guide:

At a glance: all vs allSettled vs race (and any)
Promise.all: success path and order
Promise.all short-circuits on the first rejection
Promise.allSettled: every outcome, always fulfills
Practical allSettled pattern: keep the good results
Promise.race: first settle wins (fulfill or reject)
Timeout with Promise.race
Promise.any: first fulfill, ignore rejects (brief)
Empty iterables: the sharp edges
When to use each (decision guide)
Node versions I checked
Frequently asked questions

At a glance: all vs allSettled vs race (and any)

Method	Waits for	On first reject	Result shape	Empty input
`Promise.all`	All fulfill (or first reject)	Rejects immediately with that reason	Array of values, same order	Fulfills with `[]`
`Promise.allSettled`	All settle	Keeps waiting	Array of `{status, value	reason}`
`Promise.race`	First to settle	Rejects if that first settle is a reject	That one value or reason	Pending forever
`Promise.any`	First fulfill	Ignores rejects until all fail	First value, or `AggregateError`	`AggregateError` with empty errors

I include Promise.any briefly because teams often reach for race when they meant "first success". They are not the same. A quick rule of thumb: if a single failure should fail the request, reach for all. If you are aggregating independent sources and can show a partial UI, reach for allSettled. If you are racing a timer, reach for race. If you are trying mirrors or fallbacks and only need one good answer, reach for any.

All four methods accept thenables and plain values as well as Promises. A plain string is treated as an already-fulfilled value. That is handy in tests, and it is how mixed arrays like [fetch(url), "cached"] still make sense as a list of outcomes.

Promise.all: success path and order

Promise.all takes an iterable of promises (or thenables / plain values) and fulfills with an array of results in the same order as the input, not the order they finished:

const stamp = () => Date.now();
const t0 = stamp();
const result = await Promise.all([
  delay(40, 'a'),
  delay(20, 'b'),
  delay(60, 'c'),
]);
console.log('result:', result);
console.log('elapsed_ms:', stamp() - t0);

result: [ 'a', 'b', 'c' ]
elapsed_ms: 61

Elapsed time tracked the slowest promise (~60 ms), and the array stayed ['a','b','c'] even though 'b' finished first. Another check with a slow first slot and a fast second slot still returned ['first-slot', 'second-slot']. MDN's Promise.all page describes this ordering rule.

Promise.all short-circuits on the first rejection

This is the behaviour that surprises people. The returned promise rejects as soon as any input rejects. Other work is not cancelled; all just stops waiting for it:

const t0 = Date.now();
const flags = { a: false, b: false, c: false };
try {
  await Promise.all([
    delay(80, 'a').then((v) => { flags.a = true; return v; }),
    delay(20, 'boom', true).then((v) => { flags.b = true; return v; }),
    delay(100, 'c').then((v) => { flags.c = true; return v; }),
  ]);
} catch (e) {
  console.log('caught:', e.message);
  console.log('elapsed_ms:', Date.now() - t0);
  await delay(120, 'wait');
  console.log('flags_after_wait:', flags);
}

caught: boom
elapsed_ms: 21
flags_after_wait: { a: true, b: false, c: true }

Rejection arrived at ~20 ms with the fast failure. After a short wait, a and c had still run to completion. all does not abort in-flight work. If you need cancellation, wire AbortController into the underlying tasks yourself.

Use all when the batch is useless without every result: loading config that must all succeed, or a transaction-style fan-out where one failure should fail the request.

One more detail from the run: the rejected branch never set flags.b = true, because the .then on that promise never ran; the rejection skipped it. The other two .then callbacks still ran later. So "fail fast" describes the combined promise, not the sibling tasks. Logging, metrics and lock releases inside those siblings still need their own try/finally or AbortSignal handling.

Wrapping Promise.all in try/catch with async/await is the usual style in application code. The catch receives the first rejection reason, which is often an Error but can be any thrown value.

Promise.allSettled: every outcome, always fulfills

allSettled waits for every promise to settle and fulfills with a status object for each. Rejections become data, not an exception from allSettled itself:

const t0 = Date.now();
const result = await Promise.allSettled([
  delay(40, 'ok'),
  delay(20, 'nope', true),
  delay(60, 42),
]);
console.log('elapsed_ms:', Date.now() - t0);
for (const r of result) {
  if (r.status === 'fulfilled') console.log('fulfilled:', r.value);
  else console.log('rejected:', r.reason.message);
}

elapsed_ms: 59
fulfilled: ok
rejected: nope
fulfilled: 42

Elapsed time matched the slowest input (~60 ms), not the first rejection. Fulfilled entries have value; rejected entries have reason. See MDN's Promise.allSettled reference for the exact shape.

Practical allSettled pattern: keep the good results

A common API fan-out wants every response it can get:

const urls = ['ok', 'bad', 'ok2'];
const settled = await Promise.allSettled(
  urls.map(async (u) => {
    if (u === 'bad') throw new Error('404 ' + u);
    return 'fetched ' + u;
  })
);
const ok = settled.filter((r) => r.status === 'fulfilled').map((r) => r.value);
const bad = settled.filter((r) => r.status === 'rejected').map((r) => r.reason.message);
console.log('ok:', ok);
console.log('bad:', bad);

ok: [ 'fetched ok', 'fetched ok2' ]
bad: [ '404 bad' ]

Use allSettled for dashboards, health checks, "fetch these ten feeds", or anything where partial success is still useful. If a rejected reason isn't an Error, log it as-is; don't assume .message always exists.

A small helper I use in scripts:

function partitionSettled(settled) {
  return {
    values: settled.filter((r) => r.status === 'fulfilled').map((r) => r.value),
    reasons: settled.filter((r) => r.status === 'rejected').map((r) => r.reason),
  };
}

Pass the array from allSettled straight in. You get two lists and no thrown exception. That is usually easier to render than unpacking status objects inline in JSX or a template.

Promise.race: first settle wins (fulfill or reject)

race settles with the first input that settles, whether that settle is a fulfill or a reject:

const t0 = Date.now();
const result = await Promise.race([
  delay(80, 'slow'),
  delay(20, 'fast'),
  delay(40, 'mid'),
]);
console.log('result:', result);
console.log('elapsed_ms:', Date.now() - t0);

result: fast
elapsed_ms: 20

When the fastest promise rejects, the race rejects:

const t0 = Date.now();
try {
  await Promise.race([
    delay(80, 'slow-ok'),
    delay(15, 'fast-fail', true),
    delay(40, 'mid-ok'),
  ]);
} catch (e) {
  console.log('caught:', e.message);
  console.log('elapsed_ms:', Date.now() - t0);
}

caught: fast-fail
elapsed_ms: 14

MDN's Promise.race page is the short official description. The classic use is a timeout wrapper: race your work against a rejecting timer.

Timeout with Promise.race

Here's a tiny timeout helper built on race:

function withTimeout(promise, ms) {
  let timer;
  const timeout = new Promise((_, reject) => {
    timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms);
  });
  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

// usage sketch:
// await withTimeout(fetch(url), 2000);

Clearing the timer in finally avoids leaking handles when the real work wins. Remember that losing the race does not cancel fetch unless you also pass an AbortSignal. For "wait until the first success, ignore earlier failures", use Promise.any instead of race.

I also use race for "prefer cache, but don't wait forever":

const data = await Promise.race([
  readCache(key),                 // may fulfill fast
  delay(50, null).then(() => null) // give up on cache
]);
if (data == null) {
  // fall through to network
}

If the cache is slow or missing, the timer wins with null and you continue. If the cache is warm, you skip the network. Pairing that with allSettled is overkill; race is the right shape for "first useful signal".

Promise.any: first fulfill, ignore rejects (brief)

Promise.any fulfills with the first fulfilled value and only rejects when every input rejects, via AggregateError:

const t0 = Date.now();
const result = await Promise.any([
  delay(20, 'first-fail', true),
  delay(50, 'winner'),
  delay(80, 'late'),
]);
console.log('result:', result);
console.log('elapsed_ms:', Date.now() - t0);

result: winner
elapsed_ms: 50

try {
  await Promise.any([
    delay(10, 'a', true),
    delay(20, 'b', true),
  ]);
} catch (e) {
  console.log('name:', e.name);
  console.log('errors:', e.errors.map((x) => x.message));
}

name: AggregateError
errors: [ 'a', 'b' ]

That is the opposite of race when early failures are noise. MDN documents it under Promise.any. It exists on Node 18+, 20+ and 24 in my checks.

A practical "try these mirrors" sketch:

const mirrors = [
  fetch('https://mirror-a.example/file'),
  fetch('https://mirror-b.example/file'),
  fetch('https://mirror-c.example/file'),
];
const res = await Promise.any(mirrors);
// first 2xx/ok response body wins; early network errors are ignored

I did not hit real mirrors in this batch; the timing tests used delay instead. The control flow matches what you want for CDN fallbacks: ignore early failures, take the first success, and only fail when every mirror fails.

Empty iterables: the sharp edges

Empty input is where these methods disagree the most:

console.log('all []:', await Promise.all([]));
console.log('allSettled []:', await Promise.allSettled([]));

let raceSettled = false;
const raceP = Promise.race([]);
raceP.then(() => { raceSettled = true; }, () => { raceSettled = true; });
await delay(50, 'tick');
console.log('race [] settled within 50ms?', raceSettled);

try {
  await Promise.any([]);
} catch (e) {
  console.log('any [] name:', e.name, 'errors length:', e.errors.length);
}

all []: []
allSettled []: []
race [] settled within 50ms? false
any [] name: AggregateError errors length: 0

all and allSettled treat "nothing to wait for" as done. race([]) never settles. any([]) rejects immediately with an empty AggregateError. Guard empty lists before you race them. Inside an async mapper, reading a property off undefined is a different crash; see Cannot read properties of undefined.

When to use each (decision guide)

Promise.all — every result is required; one failure should fail the whole operation.
Promise.allSettled — you want a report of successes and failures; partial data is useful.
Promise.race — timeouts, first response wins, or "whichever finishes first, good or bad".
Promise.any — first success wins; early failures should be ignored.

If you catch yourself writing nested try/catch around Promise.all just to keep going after a failure, stop and switch to allSettled. If you catch yourself writing race and then ignoring rejections manually, stop and switch to any. The methods already encode those policies; re-implementing them by hand is how subtle timing bugs creep in.

If you call something that isn't a function while mapping promises, you'll see a different error. My post on TypeError: X is not a function covers that.

Node versions I checked

All timings above are from Node.js 24.22.1 running test/js/demo.mjs. Quick existence checks:

// Node 20.20.2 and 18.20.8 both printed:
{
  all: 'function',
  allSettled: 'function',
  race: 'function',
  any: 'function'
}

allSettled and any are widely available in modern Node and current browsers. If you still support very old engines, check your baseline before relying on any. The combinators themselves are part of the language; Node's globals documentation lists Promise among the standard globals.

For day-to-day debugging I keep the four one-liners nearby:

await Promise.all(tasks) for all-or-nothing
await Promise.allSettled(tasks) for a full report
await Promise.race([work, timeout]) for deadlines
await Promise.any(mirrors) for first success

Everything else is choosing the right one for the failure mode you actually want, then testing it with deliberate delays the way I did above.

Frequently asked questions

What is the difference between Promise.all and Promise.allSettled?

Promise.all fulfills with all values or rejects on the first rejection. Promise.allSettled always fulfills with an array of status objects describing each outcome, and never rejects just because an input rejected.

Does Promise.all cancel the other promises when one fails?

No. It rejects your combined promise early, but the other async work keeps running unless you cancel it yourself (for example with AbortController).

When should I use Promise.race?

Use race for timeouts or when the first settled result should win, including failures. If you only care about the first success, use Promise.any instead.

What does Promise.any do that race does not?

any ignores rejections until every input has rejected, then throws AggregateError. race settles on the first rejection or fulfillment, whichever comes first.

What happens with Promise.all([])?

It fulfills immediately with an empty array. allSettled([]) does the same. race([]) stays pending. any([]) rejects with AggregateError.

Is the result order of Promise.all the finish order?

No. Results stay in input order. A faster second promise still lands in index 1.

How do I collect only successful results from allSettled?

Filter for status === 'fulfilled' and map to .value. Map rejected entries via .reason for logging.

Can I use these with async/await?

Yes. await Promise.all(...), await Promise.allSettled(...), and so on. The await just waits on the combined promise the method returns.

Last checked: 6 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

KeyError: 'x' in Python: 10 Causes and Fixes (dict, .get, JSON, pandas tips)

Mahir Faysal — Mon, 09 Nov 2026 15:47:28 +0000

Python raises KeyError: 'x' when you look up a key that isn't in a mapping (usually a dict) with square brackets, as in d["x"]. The quickest fixes are d.get("x") (returns None or a default), if "x" in d before you index, setdefault / defaultdict when you're building the mapping, or a narrow try/except KeyError. For JSON and pandas, check the real keys or columns first, because a missing field or a capital letter is enough to trigger the same exception.

The Python docs list KeyError as the exception raised when a mapping (dictionary) key is not found in the set of existing keys. That's the whole story. The hard part is working out why the key isn't there: a typo, the wrong nesting level, a JSON field that never arrived, or a pandas label you thought was a column.

I reproduced every example below on Python 3.13.5, and I re-ran the basic missing-key traceback on 3.11.17 and 3.14.8. All three printed the same message and caret underlining. The pandas examples used pandas 3.0.6 on 3.13.5. Paths in the tracebacks point at my test scripts under /workspace/seo-posts-nov06/test/python/.

In this guide:

What KeyError looks like
The 10 causes at a glance
1. A missing key with square brackets
2. A typo or case-sensitive key
3. Nested dicts: the crash is often one level up
4. JSON that doesn't include the field you expect
5. Hidden whitespace or odd characters in keys
6. Building a dict with zip when a value is missing
7. Reading a key you already deleted
8. Mutating a dict while you iterate (related RuntimeError)
9. pandas Series and DataFrame KeyError
10. Treating a list like a dict (and the KeyError that follows)
Reliable fixes: get, setdefault, defaultdict, try/except
Quick checklist before you ship
Frequently asked questions

What KeyError looks like

Here's the smallest crash. The dict has name and role, but not email:

user = {"name": "Ana", "role": "admin"}
print(user["email"])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c01_missing.py", line 3, in <module>
    print(user["email"])
          ~~~~^^^^^^^^^
KeyError: 'email'

Since Python 3.11, the traceback underlines the lookup. The tildes sit under user and the carets under ["email"], so you know which expression failed. The exception argument is the missing key itself: 'email'. That detail matters when you catch the error later.

The same traceback printed on 3.11.17 and 3.14.8. If you've also hit TypeError: 'NoneType' object is not subscriptable, that's a different bug: the variable was None, not a dict with a missing key. My post on TypeError: NoneType is not subscriptable covers that family of crashes.

The 10 causes at a glance

#	Cause	How to spot it	Fix
1	Missing dict key with `[]`	`KeyError: 'email'`	`.get`, `in`, or default
2	Typo or wrong case	Key looks right but isn't	Print `d.keys()`; normalize case
3	Nested dict, wrong level	Carets under the middle lookup	Step down one level at a time
4	JSON field never present	Crash after `json.loads`	Validate keys; use `.get`
5	Whitespace or hidden characters in keys	`repr(k)` shows spaces	Strip / normalize keys
6	Partial `zip` / unpack into a dict	Fewer values than headers	Check lengths before zipping
7	Deleting keys, then reading them	Key gone after `pop`/`del`	`pop(key, default)`
8	Mutating a dict while iterating	`RuntimeError` (related)	Iterate over `list(d)`
9	pandas Series / DataFrame label miss	`KeyError` from pandas	Check `columns` / use `.get`
10	Treating a list like a dict	`TypeError`, then a later KeyError	Use integer indexes or a real dict

1. A missing key with square brackets

Square-bracket lookup is strict. If the key isn't there, Python raises. That strictness is useful when a missing value should stop the program, and annoying when the key is optional.

Fix: use .get, test with in, or catch KeyError narrowly:

user = {"name": "Ana", "role": "admin"}
print("email" in user)
print(user.get("email"))
print(user.get("email", "n/a"))
print(user.get("name", "n/a"))

False
None
n/a
Ana

dict.get(key) returns None when the key is missing. Pass a second argument if you want a real default instead. The mapping types section of the Python built-in types docs covers get, setdefault and pop.

2. A typo or case-sensitive key

Dict keys are case-sensitive and compared by exact value. "Host" is not "host":

config = {"host": "localhost", "port": 5432}
print(config["Host"])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c02_typo.py", line 3, in <module>
    print(config["Host"])
          ~~~~~~^^^^^^^^
KeyError: 'Host'

Fix: print the real keys with list(config) or config.keys() before you guess. If you ingest keys from users or files, normalize them once:

cfg = {"API_KEY": "secret", " host": "x"}
print("keys repr:", [repr(k) for k in cfg])
norm = {k.strip().lower(): v for k, v in cfg.items()}
print("normalized host:", norm["host"])
print("normalized api_key:", norm["api_key"])

keys repr: ["'API_KEY'", "' host'"]
normalized host: x
normalized api_key: secret

Without normalizing, both cfg["api_key"] and cfg["host"] raised KeyError in my run because of case and a leading space. Lists, tuples, sets and dicts each compare membership differently; if you're choosing a structure, see list vs tuple vs set vs dict.

3. Nested dicts: the crash is often one level up

Chained lookups fail at the first missing key. The traceback's carets tell you which level broke:

payload = {"user": {"id": 7}}
print(payload["user"]["profile"]["avatar"])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c03_nested.py", line 3, in <module>
    print(payload["user"]["profile"]["avatar"])
          ~~~~~~~~~~~~~~~^^^^^^^^^^^
KeyError: 'profile'

There is no profile, so Python never reaches ["avatar"]. Fix: step down carefully, or chain .get with empty-dict defaults:

payload = {"user": {"id": 7}}
avatar = payload.get("user", {}).get("profile", {}).get("avatar")
print(avatar)

None

If a missing nest should be an error, keep the strict [] lookup and handle KeyError at the boundary of your function instead of burying defaults everywhere.

4. JSON that doesn't include the field you expect

json.loads gives you a plain dict (or list). It does not invent keys. A response that looks fine in the browser can still omit a field:

import json
raw = '{"ok": true, "items": []}'
data = json.loads(raw)
print(data["result"])

Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c04_json.py", line 5, in <module>
    print(data["result"])
          ~~~~^^^^^^^^^^
KeyError: 'result'

Fix: inspect data.keys(), prefer .get for optional fields, and validate required ones up front:

import json
data = json.loads('{"ok": true, "items": []}')
required = ("ok", "items")
missing = [k for k in required if k not in data]
if missing:
    raise ValueError(f"JSON missing keys: {missing}")
result = data.get("result", None)
print("ok:", data["ok"], "result:", result)

ok: True result: None

The standard library json module documents how objects decode into dicts. Schema libraries help for bigger APIs; for small scripts, an explicit required-key check is enough.

5. Hidden whitespace or odd characters in keys

This one looks identical to a typo in the editor, but repr gives it away. A leading space, a trailing newline from a CSV, or a non-breaking space from a web form will not match the clean key you typed.

cfg = {"API_KEY": "secret", " host": "x"}
print("keys repr:", [repr(k) for k in cfg])
try:
    print(cfg["host"])
except KeyError as e:
    print("KeyError whitespace:", repr(e))

keys repr: ["'API_KEY'", "' host'"]
KeyError whitespace: KeyError('host')

Fix: normalize once when you build the dict (strip(), maybe lower()), and keep the rest of the code on the cleaned keys. Logging repr(list(d)) for five seconds saves an hour of staring at identical-looking strings. When you're pasting JSON payloads while debugging, the helpers on mfaysal.com/free-tools are handy for a quick look.

6. Building a dict with zip when a value is missing

dict(zip(headers, values)) stops at the shorter sequence. Missing values quietly disappear, and the later lookup raises:

headers = ["name", "role", "email"]
values = ["Ana", "admin"]  # missing email
record = dict(zip(headers, values))
print("partial record:", record)
print(record["email"])

partial record: {'name': 'Ana', 'role': 'admin'}
Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c08_list_as_dict.py", line 13, in <module>
    print(record["email"])
          ~~~~~~^^^^^^^^^
KeyError: 'email'

Fix: compare lengths before you zip, or fill defaults:

headers = ["name", "role", "email"]
values = ["Ana", "admin"]
if len(values) < len(headers):
    values = list(values) + [None] * (len(headers) - len(values))
record = dict(zip(headers, values))
print(record)

{'name': 'Ana', 'role': 'admin', 'email': None}

The KeyError moved from "mystery crash" to an explicit None you can test. That is usually what you want when parsing rows from a file or a spreadsheet export.

7. Reading a key you already deleted

After del or pop, the key is gone. A later [] lookup raises the same KeyError as if it never existed:

d2 = {"a": 1, "b": 2}
keys = list(d2.keys())
for k in keys:
    d2.pop(k)
print("after safe pop:", d2)
print(d2["a"])

after safe pop: {}
Traceback (most recent call last):
  File "/workspace/seo-posts-nov06/test/python/c16_pop_keyerror.py", line 6, in <module>
    print(d2["a"])
          ~~^^^^^
KeyError: 'a'

Fix: use pop(key, default) when absence is normal:

user = {"name": "Ana"}
print("role:", user.pop("role", "guest"))
print("after pop:", user)

role: guest
after pop: {'name': 'Ana'}

That pattern removes the key if present and returns the default if not, without raising.

8. Mutating a dict while you iterate (related RuntimeError)

Deleting keys during a for k in d loop is not a KeyError, but it shows up in the same debugging sessions. Python refuses to keep iterating a dict whose size changed:

d = {"a": 1, "b": 2, "c": 3}
try:
    for k in d:
        if k == "b":
            del d[k]
except RuntimeError as e:
    print("RuntimeError:", e)

RuntimeError: dictionary changed size during iteration

Fix: iterate over a snapshot: for k in list(d):. Collect keys to delete, then delete them after the loop. Mixing "iterate" and "mutate" is how you get confusing crashes next to real KeyErrors.

9. pandas Series and DataFrame KeyError

pandas reuses the name KeyError when a label isn't in an index or columns. I used pandas 3.0.6:

import pandas as pd
s = pd.Series([10, 20, 30], index=["a", "b", "c"])
print("s['b'] =", s["b"])
print(s["d"])

s['b'] = 20
KeyError: 'd'

Columns are the same story. Name is not name:

df = pd.DataFrame({"name": ["Ana", "Bo"], "score": [9, 7]})
print("columns:", list(df.columns))
print(df["Name"])

columns: ['name', 'score']
KeyError: 'Name'

Label selection with .loc and .at also raises KeyError for a missing label. Position-based .iloc does not look up by name:

print("iloc[0]:", df.iloc[0].tolist())
# df.loc[5]  -> KeyError: 5
# df.at[0, "email"] -> KeyError: 'email'

iloc[0]: ['Ana', np.int64(9)]

Fix: print df.columns / s.index, use df.get("Name") for optional columns (returns None), or select by position with iloc when you mean "first row", not "row labelled 0". The pandas indexing guide covers label vs position in detail.

10. Treating a list like a dict (and the KeyError that follows)

Sometimes the first crash isn't a KeyError at all. Indexing a list with a string raises TypeError. People then convert with zip, hit cause 6, and land on KeyError anyway:

row = ["Ana", "admin"]
try:
    print(row["name"])
except TypeError as e:
    print("TypeError:", e)

TypeError: list indices must be integers or slices, not str

Fix: decide on one shape. If you need named fields, build a real dict (and check lengths). If you need a sequence, use integer indexes. Mixing the two is how optional CSV columns turn into production KeyErrors.

Reliable fixes: get, setdefault, defaultdict, try/except

Four patterns cover almost every dict KeyError I see:

from collections import defaultdict

user = {"name": "Ana"}

# 1) Optional read
email = user.get("email", "unknown@example.com")

# 2) Narrow catch when absence is exceptional at this layer
try:
    role = user["role"]
except KeyError:
    role = "guest"

# 3) setdefault while building counts
counts = {}
for word in ["a", "b", "a"]:
    counts.setdefault(word, 0)
    counts[word] += 1

# 4) defaultdict when missing keys should create a value
groups = defaultdict(list)
for name, team in [("Ana", "blue"), ("Bo", "red"), ("Cy", "blue")]:
    groups[team].append(name)

print(email, role, counts, dict(groups))

unknown@example.com guest {'a': 2, 'b': 1} {'blue': ['Ana', 'Cy'], 'red': ['Bo']}

defaultdict is documented in the collections module. Prefer it when "missing means create", and prefer plain .get when "missing means default without inserting". Blind except Exception is worse than a narrow except KeyError, because it hides real bugs next to missing keys.

Quick checklist before you ship

Read the caret line: which lookup failed?
Print list(d) or repr(list(d)) once.
For JSON, list required keys and reject early.
For pandas, confirm columns / index labels; don't assume case.
Use .get / in for optional keys; keep [] for required ones.
Don't mutate a dict while iterating it.

If the traceback instead says a module is missing, that's ModuleNotFoundError, not KeyError. See ModuleNotFoundError: No module named ... for that path.

Frequently asked questions

What does KeyError: 'x' mean in Python?

It means you used square brackets to look up the key 'x' on a mapping (usually a dict), and that key is not present. The string inside the exception is the missing key.

What is the difference between d['x'] and d.get('x')?

d['x'] raises KeyError if 'x' is missing. d.get('x') returns None instead. d.get('x', default) returns your default. Use [] for required keys and get for optional ones.

Why do I get KeyError on a nested dict when the outer key exists?

Chained lookups fail at the first missing key. payload['user']['profile'] raises KeyError: 'profile' when user exists but profile does not. Check the caret underline in the traceback.

How do I fix KeyError after json.loads?

json.loads only creates keys that were in the JSON text. Print data.keys(), require the fields you need, and use .get for optional ones.

Why does pandas raise KeyError for a column I can see?

Column names are exact. 'Name' is not 'name'. Print list(df.columns). For optional columns, df.get('Name') returns None instead of raising.

Is catching KeyError a bad practice?

A narrow except KeyError at a boundary is fine. A bare except or except Exception that swallows everything is not. Prefer .get or 'in' when absence is a normal case.

KeyError vs TypeError: list indices must be integers?

If you index a list with a string, you get TypeError, not KeyError. KeyError is for missing keys on mappings (and pandas labels). Convert to a dict only when you have matching headers and values.

Does KeyError happen with sets or tuples?

Sets and tuples are not mappings. Looking up with [] on a set fails differently; on a tuple you use integer indexes. KeyError is the missing-key exception for dict-like objects.

Last checked: 6 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

TypeScript interface vs type: Differences, Declaration Merging and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:47:01 +0000

In TypeScript, interface and type are interchangeable for most object shapes. The real differences are these. Interfaces can be declared more than once and merge (declaration merging), and extends reports property conflicts. Type aliases can name anything, including unions, tuples, primitives, mapped and conditional types, but they can't be reopened. A good default: use interface for object shapes and public APIs, and type for unions and computed types.

The TypeScript Handbook section on differences between type aliases and interfaces gives the short version. This guide shows each difference with code I compiled myself, including the exact errors you'll see when you hit the edges.

I compiled every example with TypeScript 7.0.2 (the new native compiler) and 5.9.3 using --strict, on Node.js 24.22.1. Both versions printed identical error messages. The only difference was the exit code: 1 on 7.0.2 and 2 on 5.9.3.

In this guide:

interface vs type at a glance
Where they behave the same
1. Declaration merging: only interfaces can be reopened
The accidental merge trap
2. extends vs intersection: how conflicts are reported
3. Unions, tuples, mapped and conditional types need type
4. implements works with both, with one catch
5. You can mix them freely
6. Implicit index signatures: a surprising difference
7. Error messages: interfaces keep their names
8. Performance: prefer interfaces for composition
Which should you use?
How I tested these examples
Frequently asked questions

interface vs type at a glance

Feature	interface	type
Describe an object shape	Yes	Yes
Function and method signatures	Yes	Yes
Declaration merging (reopen it later)	Yes	No: Duplicate identifier error
Extend or combine	`extends`, conflicts reported	`&`, conflicts become `never`
Unions, tuples, primitives	No	Yes
Mapped, conditional, template literal types	No	Yes
Used with `implements`	Yes	Yes, if it's an object type (not a union)
Assignable to `Record<string, string>`	No implicit index signature	Yes
Name kept in error messages	Consistently	Can expand into the full structure
Checking speed for big compositions	Faster (cached)	Intersections can be slower

Where they behave the same

For a plain object shape, the two forms are fully interchangeable. TypeScript compares types by structure, not by name, so a value of one fits the other:

interface UserI {
  id: number;
  name: string;
}

type UserT = {
  id: number;
  name: string;
};

const a: UserI = { id: 1, name: 'Mahir' };
const b: UserT = a; // fine: TypeScript compares shapes, not names
const c: UserI = b; // also fine

This compiled with no errors on both versions. Function types work either way too:

interface FormatI {
  (value: number): string;
}
type FormatT = (value: number) => string;

const toGBP: FormatI = (v) => `£${v.toFixed(2)}`;
const toUSD: FormatT = (v) => `$${v.toFixed(2)}`;

$ node t12_functions.ts
£4.50 $4.50

Node 24 ran the .ts file directly with type stripping, with no build step. Type stripping only removes annotations and never type-checks, so you still need tsc to catch the errors below. The choice between the two keywords matters in the edge cases that follow.

1. Declaration merging: only interfaces can be reopened

Declare an interface twice in the same scope and TypeScript merges the two into one. Try the same with a type alias and you get an error:

interface Settings {
  theme: string;
}
interface Settings {
  fontSize: number;
}

// Both declarations merged into one interface
const s: Settings = { theme: 'light', fontSize: 16 };
const missing: Settings = { theme: 'dark' };

type Options = { theme: string };
type Options = { fontSize: number };

$ npx tsc --noEmit --strict --lib ES2022,DOM t02_merging.ts
t02_merging.ts(10,7): error TS2741: Property 'fontSize' is missing in type '{ theme: string; }' but required in type 'Settings'.
t02_merging.ts(12,6): error TS2300: Duplicate identifier 'Options'.
t02_merging.ts(13,6): error TS2300: Duplicate identifier 'Options'.

The first error proves the merge happened: Settings now needs fontSize as well. The main real-world use is adding to types you don't own, such as the global Window:

declare global {
  interface Window {
    appVersion: string;
  }
}

window.appVersion = '1.4.2';

That compiled cleanly. Library type definitions use the same trick to let you extend things like Express's Request. The handbook page on declaration merging covers the full rules.

The accidental merge trap

Merging also has a downside. In a file with no import or export, your declarations are global, and with the DOM types loaded, Comment already exists. It's the DOM's comment node. Declare your own Comment interface and it silently merges with that one:

// No import/export: this file is a global script, so Comment merges with the DOM's Comment
interface Comment {
  id: number;
  text: string;
}

const c: Comment = { id: 1, text: 'Nice post' };

t10_global_clash.ts(7,7): error TS2740: Type '{ id: number; text: string; }' is missing the following properties from type 'Comment': data, length, ownerDocument, appendData, and 59 more.

The error points at the object, not at the declaration that caused it, which makes it confusing. A type alias with the same name fails loudly where it's declared:

t10b_global_clash_type.ts(2,6): error TS2300: Duplicate identifier 'Comment'.

The fix for both is to make the file a module with an import or export, or to pick a less generic name. If modules and import errors are new to you, my post on Cannot use import statement outside a module explains how Node decides what counts as a module.

2. extends vs intersection: how conflicts are reported

You can build on an interface with extends, or on a type with &. They agree until two members clash:

interface Animal {
  id: string;
  name: string;
}

// interface extends: the conflict is reported right here
interface Dog extends Animal {
  id: number;
}

// type intersection: no error here, id silently becomes never
type Cat = Animal & { id: number };

const cat: Cat = { id: 1, name: 'Tom' };

$ npx tsc --noEmit --strict --lib ES2022,DOM t04_extends_conflict.ts
t04_extends_conflict.ts(7,11): error TS2430: Interface 'Dog' incorrectly extends interface 'Animal'.
  Types of property 'id' are incompatible.
    Type 'number' is not assignable to type 'string'.
t04_extends_conflict.ts(14,20): error TS2322: Type 'number' is not assignable to type 'never'.

With extends, the error lands on the declaration and explains the clash. With &, the declaration is accepted, id becomes string & number, which is never, and you only find out later when no value fits. That's a strong reason to prefer extends when you build object types from other object types. Catching shape mistakes at compile time is the point of TypeScript. In plain JavaScript they surface at runtime, as errors like TypeError: x is not a function.

3. Unions, tuples, mapped and conditional types need type

An interface can only describe an object shape. Everything else needs a type alias:

type ID = string | number;                         // union
type Point = [x: number, y: number];               // tuple
type Status = 'idle' | 'loading' | 'done';         // literal union
type Flags<T> = { [K in keyof T]: boolean };       // mapped type
type ElementOf<T> = T extends (infer U)[] ? U : T; // conditional type
type EventName = `on${Capitalize<'click' | 'focus'>}`; // template literal

$ node t05_type_only.ts
42 [ 10, 20 ] done { dark: true, beta: false } hello onClick

All six compiled and ran. Mapped types like Flags are explained in the handbook chapter on mapped types. An interface also can't extend a union, because a union isn't one object shape:

interface Success { ok: true; data: string }
interface Failure { ok: false; error: string }

type Result = Success | Failure;

// An interface cannot be a union, and cannot extend one
interface Result2 extends Result {}

t06_interface_union.ts(7,27): error TS2312: An interface can only extend an object type or intersection of object types with statically known members.

The usual pattern is the one above: an interface for each variant, and a type alias for the union of them.

4. implements works with both, with one catch

A class can implement an interface or an object type alias, and even both at once:

interface Greeter {
  greet(name: string): string;
}
type Logger = {
  log(message: string): void;
};

// A class can implement both an interface and an object type alias
class Service implements Greeter, Logger {
  greet(name: string) { return `Hello, ${name}`; }
  log(message: string) { console.log(message); }
}

type Shape = { kind: 'circle'; r: number } | { kind: 'square'; size: number };

class Circle implements Shape {
  kind = 'circle' as const;
  r = 1;
}

t07_implements.ts(16,25): error TS2422: A class can only implement an object type or intersection of object types with statically known members.

Service was fine. Circle failed because Shape is a union, and a class must match one known shape. The handbook chapter on classes notes another point: implements only checks the class. It doesn't change the types inside it.

5. You can mix them freely

The two forms work together. An interface can extend an object type alias, and a type alias can intersect an interface:

type Timestamps = { createdAt: Date; updatedAt: Date };

interface Post extends Timestamps {
  title: string;
}

type Draft = Post & { published: false };

That compiled cleanly and ran under Node. You don't have to choose one keyword for a whole codebase.

6. Implicit index signatures: a surprising difference

This one catches people out. A type alias for an object literal type can be passed where a Record<string, string> is expected. An interface with exactly the same members can't:

interface HeadersI {
  accept: string;
}
type HeadersT = {
  accept: string;
};

function send(headers: Record<string, string>) {
  console.log(headers);
}

const h1: HeadersT = { accept: 'text/html' };
const h2: HeadersI = { accept: 'text/html' };

send(h1); // OK: type aliases get an implicit index signature
send(h2); // Error: interfaces do not

t09_index_signature.ts(16,6): error TS2345: Argument of type 'HeadersI' is not assignable to parameter of type 'Record<string, string>'.
  Index signature for type 'string' is missing in type 'HeadersI'.

The reason is merging. Because an interface can be reopened later with more members, TypeScript won't assume every member is a string. If you hit this, use a type alias, add an index signature to the interface, or type the parameter more precisely. Record is one of the built-in utility types.

7. Error messages: interfaces keep their names

Interface names show up consistently in errors and editor tooltips. Type aliases built from intersections can expand into their full structure once they're combined with something else:

interface Base { id: number; name: string; secret: string }

interface PublicUserI extends Omit<Base, 'secret'> { avatar: string }
type PublicUserT = Omit<Base, 'secret'> & { avatar: string };

declare const i: PublicUserI;
declare const t: PublicUserT;

function withRole<T>(user: T) {
  return { ...user, role: 'admin' as const };
}

const r1: number = withRole(i);
const r2: number = withRole(t);

t13_error_display.ts(13,7): error TS2322: Type 'PublicUserI & { role: "admin"; }' is not assignable to type 'number'.
t13_error_display.ts(14,7): error TS2322: Type 'Omit<Base, "secret"> & { avatar: string; } & { role: "admin"; }' is not assignable to type 'number'.

The two types describe the same values, but the second message makes you read Omit<Base, "secret"> and work out what it means. In a large codebase, that adds up. For simple cases TypeScript keeps alias names too, so this mainly matters for intersections.

8. Performance: prefer interfaces for composition

The TypeScript team's Performance wiki page has a section called "Preferring Interfaces Over Intersections". It says interfaces create a single flat object type that detects property conflicts, that type relationships between interfaces are cached while intersection types as a whole are not, and that every part of a target intersection is checked before the flattened type. Its advice: when you compose types, extend them with an interface instead of intersecting them in a type alias.

I didn't benchmark this myself. With ten-line examples, the difference is too small to measure. It matters in big projects with deep type hierarchies, where type-checking time and editor responsiveness add up.

Which should you use?

Object shapes, props, API responses and class contracts: interface. You get clear conflict errors, consistent names in errors and the faster path for composition.
Unions, tuples, primitives, function types and anything computed: type. There's no alternative.
Adding to a library or global type: interface, because only interfaces merge.
Values passed as Record<string, ...>: type, or add an index signature.
Combining shapes: interface ... extends over & where you can.

Whatever you pick, be consistent within a project, and let a linter enforce it if your team argues about it. Plain JavaScript basics still apply underneath, so it's worth knowing the runtime side too, such as my guide to var vs let vs const.

How I tested these examples

Each snippet is its own file, compiled with tsc --noEmit --strict --lib ES2022,DOM on TypeScript 7.0.2 and 5.9.3, with Node.js 24.22.1 running the clean files. One TypeScript 7 change caught me out: with a tsconfig.json in the folder, passing a file name on the command line is now an error:

$ npx tsc t01_same_shape.ts
error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.

Either run plain tsc to use the config, or add --ignoreConfig as the message says. My free tools page has a few small browser-based helpers if you need to tidy JSON or test data while you work.

Frequently asked questions

What is the main difference between interface and type in TypeScript?

Interfaces can be declared more than once and merge, and they can only describe object shapes. Type aliases can't be reopened, but they can name any type, including unions, tuples, primitives, mapped and conditional types.

Should I use interface or type for React props?

Either works. Many teams use interface for props because errors show the name clearly and extends reports conflicts. Use a type alias when the props are a union, for example a component that accepts one of two different prop shapes.

Can a type alias extend an interface?

Not with the extends keyword, but it can intersect one: type Draft = Post & { published: false }. An interface can also extend an object type alias with extends, as long as the alias isn't a union.

Why does TypeScript say Duplicate identifier for my type?

Type aliases can't be declared twice in the same scope. You may have two type declarations with the same name, or, in a file with no import or export, a name that clashes with a global such as the DOM's Comment. Rename it or make the file a module.

Are interfaces faster than types?

For composing object types, the TypeScript team's Performance wiki recommends interfaces with extends over intersections, because interface relationships are cached and conflicts are flattened. For a simple object shape, there's no practical difference.

Can a class implement a type alias?

Yes, if the alias describes an object type or an intersection of object types. A class can't implement a union type alias. TypeScript reports error TS2422 because the class has to match one known shape.

Why can't I pass an interface to a Record parameter?

Interfaces don't get an implicit index signature, because they could be merged with more members later. A type alias with the same members does. Use a type alias, add an index signature, or change the parameter type.

Last checked: 5 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

Error: listen EADDRINUSE: address already in use in Node.js: 10 Causes and Fixes (Tested on Linux, Windows tips, nodemon)

Mahir Faysal — Mon, 09 Nov 2026 15:46:34 +0000

"Error: listen EADDRINUSE: address already in use :::3000" means another process is already listening on port 3000, so your Node.js server can't bind to it. The quick fix on Linux or macOS is to find that process with lsof -i :3000 and stop it with kill <PID>. On Windows, use netstat -ano | findstr :3000 and then taskkill /PID <PID> /F. If you need both servers running, start yours on a different port instead.

The Node.js docs on common system errors describe EADDRINUSE as a failed attempt to bind a server to a local address because another server already occupies it. The hard part is working out which server that is, because it's often a copy of your own app that you can't see.

I reproduced every cause below on Linux with Node.js 24.22.1 (plus 18, 20 and 22 for the basic error), Express 5.3.0 and 4.22.3, nodemon 3.1.14, Vite 8.3.6 and Next.js 16.4.5. All output is copied from those runs. The Windows commands are from Microsoft's docs and marked as untested.

In this guide:

What the error looks like
Quick fix: find and stop the process using the port
Windows: netstat and taskkill (not tested)
The 10 causes at a glance
1. The same app is already running in another terminal
2. A process suspended with Ctrl+Z still owns the port
3. An orphan left after nodemon or the terminal was killed
4. A Ctrl+C or SIGTERM handler that never exits
5. A nodemon restart that stalls on SIGUSR2
6. Express app.listen() called twice
7. A Next.js or Vite dev server already on that port
8. IPv4 vs IPv6: localhost is two addresses
9. A hard-coded port: use PORT or port 0
10. No error handler: retry on the next port
How to stop it happening again
Frequently asked questions

What the error looks like

Here's a minimal server, server.js:

const http = require('node:http');

const PORT = 3000;
const server = http.createServer((req, res) => {
  res.end('Hello from ' + process.pid + '\n');
});

server.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT} (pid ${process.pid})`);
});

Running it a second time while the first copy was up crashed instantly:

$ node server.js
node:events:505
    throw er; // Unhandled 'error' event
    ^

Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (node:net:2390:16)
    at listenInCluster (node:net:2499:12)
    at Object.<anonymous> (/workspace/seo-posts-nov05/test/node/server.js:8:8)
Emitted 'error' event on Server instance at:
    at emitErrorNT (node:net:2478:8)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  code: 'EADDRINUSE',
  errno: -98,
  syscall: 'listen',
  address: '::',
  port: 3000
}

Node.js v24.22.1

A few details are worth reading closely:

:::3000 is the IPv6 "any address" :: followed by :3000. Node listens on :: by default when IPv6 is available.
errno: -98 is the Linux number for this error. It differs on other systems, so check err.code in your code.
Unhandled 'error' event means nothing handled the server's error event, so Node crashed with exit code 1.

Node 18, 20 and 22 printed the same first line and code.

Quick fix: find and stop the process using the port

On Linux and macOS, lsof shows who owns the port. The -t flag prints just the PID, which is handy for scripts:

$ lsof -i :3000
COMMAND      PID USER FD   TYPE  DEVICE SIZE/OFF NODE NAME
MainThrea 283150  box 21u  IPv6 1804524      0t0  TCP *:3000 (LISTEN)
$ lsof -t -i :3000
283150

Node 24 shows up as MainThrea (MainThread, cut short), not node, so don't search the list for "node". Without lsof, ss and fuser give the same answer:

$ ss -ltnp 'sport = :3000'
State  Recv-Q Send-Q Local Address:Port Peer Address:PortProcess                                 
LISTEN 0      511                *:3000            *:*    users:(("MainThread",pid=283150,fd=21))
$ fuser 3000/tcp
3000/tcp:            283150

Check what it is before you kill it:

$ ps -o pid,ppid,etime,cmd -p 283150
    PID    PPID     ELAPSED CMD
 283150  283018       00:01 /usr/local/lib/nodejs/node server.js
$ kill 283150
$ lsof -i :3000
lsof exit code: 1

A plain kill sends SIGTERM, so the process can clean up. fuser -k 3000/tcp finds and kills in one step, but sends SIGKILL. For more ways to list listening ports, see my guide on how to check open ports.

Windows: netstat and taskkill (not tested)

I didn't run these, because my test machine is Linux. They come from Microsoft's documentation for netstat and taskkill:

In Command Prompt or PowerShell, run netstat -ano | findstr :3000. The -o flag adds the owning process ID in the last column of the LISTENING line.
Stop it with taskkill /PID 12345 /F, replacing 12345 with that PID. /F forces termination.

The 10 causes at a glance

#	Cause	How to spot it	Fix
1	The same app is running in another terminal	`lsof -i :3000` shows your own script	Stop it, or use another port
2	A process suspended with Ctrl+Z	`ps` shows state `T`; requests hang	`fg` then Ctrl+C, or `kill`
3	An orphan left after nodemon or a terminal was killed	Parent PID changed to an init process	Kill the orphan PID
4	A SIGINT/SIGTERM handler that never exits	Ctrl+C prints a message but the port stays busy	Close the server, then exit
5	A nodemon SIGUSR2 handler that never exits	Restart prints "restarting" and stalls	Use `process.once` and re-send the signal
6	Express `app.listen()` called twice	Two "listening" logs from one process	Listen in one file only
7	A Next.js or Vite dev server on the same port	Fixed port flag or `strictPort`	Stop the other server or change port
8	IPv4 and IPv6 binding overlap	Error shows `:::3000` or `127.0.0.1:3000`	Pick one host deliberately
9	A hard-coded port	Every project uses 3000	`PORT` env var, or port 0 in tests
10	No error handler on the server	"Unhandled 'error' event" crash	`server.on('error')` with a retry

1. The same app is already running in another terminal

This is the usual cause. You started the server in another terminal tab, a VS Code task or a background job, forgot about it, and started it again. The crash in the first section came from exactly this.

Fix: find the PID, confirm it's your app with ps, and stop it. If you want two copies, give the second its own port (see cause 9).

2. A process suspended with Ctrl+Z still owns the port

Ctrl+Z doesn't stop a server. It pauses it, and the paused process still owns the port. I paused one with SIGSTOP, which is what Ctrl+Z sends:

$ ps -o pid,stat,cmd -p 283234
    PID STAT CMD
 283234 Tl   /usr/local/lib/nodejs/node server.js
$ curl -m 3 http://localhost:3000
curl: (28) Operation timed out after 3001 milliseconds with 0 bytes received
$ node server.js
Error: listen EADDRINUSE: address already in use :::3000

T means stopped. A hanging request plus a busy port is the giveaway.

Fix: in the same terminal, run jobs to list paused jobs, then fg to bring it back and Ctrl+C to quit properly. From another terminal, kill -CONT <PID> resumes it and kill <PID> stops it. After I sent SIGCONT, the paused server answered again with Hello from <pid>.

3. An orphan left after nodemon or the terminal was killed

nodemon runs your app as a child process. If nodemon dies hard (kill -9, a crashed editor terminal, a dropped SSH session), the child can survive. I killed nodemon with SIGKILL and the Node process got a new parent:

$ ps -o pid,ppid,cmd -p 283361 (before)
    PID    PPID CMD
 283361  283346 /usr/local/lib/nodejs/node server.js
$ ps -o pid,ppid,cmd -p 283361 (after nodemon was killed)
    PID    PPID CMD
 283361      53 /usr/local/lib/nodejs/node server.js

Starting nodemon again then failed:

$ npx nodemon server.js
[nodemon] 3.1.14
[nodemon] starting `node server.js`
Error: listen EADDRINUSE: address already in use :::3000
[nodemon] app crashed - waiting for file changes before starting...

Fix: kill the orphan by PID (lsof -t -i :3000 finds it), then start nodemon again. Quit nodemon with Ctrl+C rather than killing it, so it can stop its child first.

4. A Ctrl+C or SIGTERM handler that never exits

Once you add your own SIGINT handler, Node stops exiting on Ctrl+C by itself. If the handler only logs or saves something, the process keeps running and keeps the port:

// Mistake: catching Ctrl+C but never closing the server or exiting
process.on('SIGINT', () => {
  console.log('Got SIGINT, saving state...');
});

$ kill -INT 284449
Got SIGINT, saving state...
$ ss -ltnH 'sport = :3000' | wc -l
1

The listener survived the "shutdown". Instead, close the server, exit when it's closed, and force an exit if connections hold it open. closeIdleConnections() and closeAllConnections() are documented in the Node.js http module reference:

function shutdown(signal) {
  console.log(`${signal} received, closing server...`);
  server.close(() => {
    console.log('server closed, port released');
    process.exit(0);
  });
  server.closeIdleConnections();
  // Safety net: force exit if open connections keep the server alive
  setTimeout(() => {
    console.log('forcing exit after 5s');
    server.closeAllConnections();
    process.exit(1);
  }, 5000).unref();
}

process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

$ kill -INT 284505
SIGINT received, closing server...
server closed, port released
$ ss -ltnH 'sport = :3000' | wc -l
0

Handle SIGTERM too, because Docker, systemd and most process managers use it instead of Ctrl+C.

5. A nodemon restart that stalls on SIGUSR2

On each restart, nodemon sends your app a signal (SIGUSR2 by default) and waits for it to exit. The nodemon README explains how to catch that signal for cleanup. If your handler catches it and doesn't exit, the restart stalls:

// Mistake: a "cleanup" handler that never lets the process exit
process.on('SIGUSR2', () => {
  console.log('SIGUSR2 received, cleaning up...');
});

[nodemon] starting `node nm-trap.js`
listening on 3000 (pid 283568)
[nodemon] restarting due to changes...
SIGUSR2 received, cleaning up...
SIGUSR2 received, cleaning up...

nodemon 3.1.14 waited for the old process, so I got a frozen restart rather than EADDRINUSE. Kill nodemon at that point and you get the orphan from cause 3. This version cleans up, then lets the signal finish the job:

// nodemon sends SIGUSR2 on restart: clean up, then let the signal kill us
process.once('SIGUSR2', () => {
  console.log('SIGUSR2 received, closing server...');
  server.close(() => process.kill(process.pid, 'SIGUSR2'));
});

[nodemon] restarting due to changes...
SIGUSR2 received, closing server...
[nodemon] starting `node nm-fixed.js`
listening on 3000 (pid 283702)

once matters here. It removes the handler after the first call, so the re-sent signal uses the default action and ends the process.

6. Express app.listen() called twice

A common Express layout has app.js build the app and index.js start it. The bug creeps in when app.js also calls listen():

// Mistake: the app module starts listening as a side effect
app.listen(3000, () => console.log('app.js: listening on 3000'));

module.exports = app;

const app = require('./app');

app.listen(3000, () => console.log('index.js: listening on 3000'));

Express 4.22.3 crashed with the usual EADDRINUSE trace. Express 5.3.0 behaved differently, and the result is confusing:

$ node express-bad/index.js  (Express 5)
app.js: listening on 3000
index.js: listening on 3000
$ ss -ltnH 'sport = :3000' | wc -l
1

Both log lines appeared, but only one server was listening. In Express 5, app.listen() passes a listen error to your callback, so a callback that ignores its argument logs "listening" even when it failed. Logging the argument shows the truth:

app.js: listening on 3000
index.js callback, err = listen EADDRINUSE: address already in use :::3000

Fix: export the app without listening, call listen() in one entry file, and always check err in Express 5. The Express 5 API reference covers app.listen().

const PORT = Number(process.env.PORT) || 3000;
const server = app.listen(PORT, (err) => {
  if (err) {
    console.error(`Could not start: ${err.code} on port ${PORT}`);
    process.exit(1);
  }
  console.log(`listening on ${PORT}`);
});

7. A Next.js or Vite dev server already on that port

Front-end dev servers handle a busy port in their own way. With port 3000 taken, Next.js 16.4.5 moved to the next free port when I didn't name one, but failed when I asked for 3000 explicitly:

$ npx next dev
⚠ Port 3000 is in use by process 284021, using available port 3001 instead.
- Local:         http://localhost:3001
$ npx next dev -p 3000
⨯ Failed to start server
Error: listen EADDRINUSE: address already in use :::3000

Vite 8.3.6 does the same. It tries the next port unless you set --strictPort or server.strictPort, and then it exits with its own message. Without the flag, it came up on 5174:

$ npx vite --host 127.0.0.1
Port 5173 is in use, trying another one...
$ npx vite --host 127.0.0.1 --strictPort
error when starting dev server:
Error: Port 5173 is already in use

The silent fallback can break a CORS allow-list, OAuth redirect URL or proxy that expects the original port. If a fixed port matters, use strict mode and stop the old process.

8. IPv4 vs IPv6: localhost is two addresses

The net module docs say that without a host, Node listens on ::, and on most systems that also covers IPv4 0.0.0.0. I used a small listen-host.js that takes a port and an optional host. With something on 127.0.0.1:3000, the default listen failed:

listening on 127.0.0.1 port 3000 (family IPv4)
$ node listen-host.js 3000
default -> EADDRINUSE: listen EADDRINUSE: address already in use :::3000

A server bound to IPv6 ::1 could share port 3000 with the IPv4 one, though, and localhost then went to the IPv6 server:

$ ss -ltn 'sport = :3000'
State  Recv-Q Send-Q Local Address:Port Peer Address:Port
LISTEN 0      511        127.0.0.1:3000      0.0.0.0:*   
LISTEN 0      511            [::1]:3000         [::]:*   
$ curl http://localhost:3000
answered by ::1

Node resolved localhost to ::1 first here. The address in the error tells you which binding clashed, so search by port with ss -ltn and choose your host on purpose.

9. A hard-coded port: use PORT or port 0

If every project uses 3000, two will collide eventually. Read the port from the environment:

const PORT = Number(process.env.PORT) || 3000;
const server = http.createServer((req, res) => res.end('ok\n'));

server.listen(PORT, () => console.log(`listening on ${server.address().port}`));

$ PORT=4567 node env-port.js
listening on 4567

For tests, listen on port 0. The operating system then picks a free port, so parallel test runs can't clash:

server.listen(0, '127.0.0.1', () => {
  const { port } = server.address();
  console.log(`OS picked free port ${port}`);
  server.close();
});

$ node port0.js
OS picked free port 42569

Read server.address() inside the listen callback. Before the server is listening, it returns null, and reading .port from it throws the kind of error covered in my post on Cannot read properties of undefined.

10. No error handler: retry on the next port

The crash says "Unhandled 'error' event" because nobody listened for it. Add a handler, and you can try the next port, much as Vite does:

server.on('error', (err) => {
  if (err.code === 'EADDRINUSE' && port < lastPort) {
    console.log(`Port ${port} is busy, trying ${port + 1}...`);
    port += 1;
    setTimeout(() => server.listen(port), 100);
  } else {
    console.error(err);
    process.exit(1);
  }
});

$ node retry.js
Port 3000 is busy, trying 3001...
Port 3001 is busy, trying 3002...
listening on http://localhost:3002

Use this for local tools only. In production, a server that quietly changes port is worse than one that fails loudly, because your proxy still points at the old one.

Node 22.12+ also accepts reusePort: true on Linux. Two processes that both set it shared port 3000 in my test, but a normal server still got EADDRINUSE. It's for load balancing, not for hiding stale processes.

How to stop it happening again

Stop dev servers with Ctrl+C, not Ctrl+Z, and don't close terminals with servers still running.
Handle SIGINT and SIGTERM by closing the server and then exiting.
Call listen() in one place only, and check the error in Express 5 callbacks.
Read the port from PORT, and use port 0 in automated tests.
Add a server.on('error') handler that prints a clear message.

For other quick developer helpers, see my free tools.

Frequently asked questions

What does EADDRINUSE mean in Node.js?

It means address already in use. Another process, often an earlier copy of your own app, is already listening on the port and address your server tried to bind, so the operating system refused the second listen() call.

How do I kill the process on port 3000?

On Linux or macOS, run lsof -i :3000 or ss -ltnp 'sport = :3000' to get the PID, check it with ps, then run kill PID. fuser -k 3000/tcp does both steps but sends SIGKILL. On Windows, netstat -ano | findstr :3000 shows the PID and taskkill /PID PID /F stops it (I didn't test the Windows commands).

Why does EADDRINUSE keep happening with nodemon?

Usually because an old copy of the app survived. That happens if nodemon was killed hard, if the app was paused with Ctrl+Z, or if another nodemon is running in a second terminal. A SIGUSR2 handler that never exits makes nodemon's restart stall instead.

Why does the error say :::3000?

The :: is the IPv6 any address, and :3000 is the port. Node listens on :: by default when IPv6 is available, which usually covers IPv4 too, so it clashes with anything on 0.0.0.0:3000 or 127.0.0.1:3000.

Is EACCES the same as EADDRINUSE?

No. EACCES means permission denied. On Linux, ports below 1024 need extra privileges, so listen(80) as a normal user gave me listen EACCES: permission denied 0.0.0.0:80. Use a port above 1024 and put a reverse proxy in front.

Can two Node.js processes listen on the same port?

Not normally. On Linux with Node 22.12+ or 23.1+, processes that all set reusePort: true can share a port, and the cluster module shares one between workers. A normal listen() on a port that's already in use still fails with EADDRINUSE.

How do I make my server pick a free port automatically?

Listen on port 0 and read server.address().port in the listen callback, or catch EADDRINUSE in server.on('error') and retry on the next port. Both are fine for local development and tests. In production, use a fixed, configured port.

Last checked: 5 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

SQL WHERE vs HAVING: Differences, Execution Order and When to Use Each (Tested Examples)

Mahir Faysal — Mon, 09 Nov 2026 15:46:07 +0000

WHERE filters individual rows before they are grouped, and HAVING filters whole groups after GROUP BY has run. That's why only HAVING can use aggregate functions such as SUM(), COUNT() and AVG(). Use WHERE for conditions on plain columns, like status = 'paid', and HAVING for conditions on totals, like SUM(amount) > 100. You can use both in one query, and WHERE always runs first.

The PostgreSQL SELECT reference puts it in one line: WHERE filters individual rows before GROUP BY is applied, while HAVING filters group rows created by GROUP BY. The rest of this guide shows what that means in practice, including the errors you get when you mix them up and a case where the wrong choice makes MySQL read the whole table.

I ran every query below on MySQL 8.4.8 (default ONLY_FULL_GROUP_BY mode), PostgreSQL 17.11 and SQLite 3.46.1. All the results and error messages are copied from those runs.

In this guide:

WHERE vs HAVING at a glance
The sample table I used
Where each clause runs in a query
WHERE: filter individual rows
HAVING: filter groups using aggregates
Why WHERE SUM(...) fails: the errors in MySQL, PostgreSQL and SQLite
Using WHERE and HAVING together
The trap: WHERE removes groups you wanted to keep
Non-aggregate conditions: same result, different cost
HAVING on a column that is not grouped
Can you use a column alias in WHERE or HAVING?
HAVING without GROUP BY
Quick rules for choosing
Frequently asked questions

WHERE vs HAVING at a glance

	WHERE	HAVING
Filters	Individual rows	Groups of rows
Runs	Before GROUP BY	After GROUP BY and aggregation
Aggregates like `SUM()`	Not allowed (error)	Allowed, and the main reason to use it
Needs GROUP BY?	No	Usually used with it; without it the whole result is one group
Works in UPDATE and DELETE	Yes	No, SELECT only
Can use indexes	Yes	Not reliably (see the performance test below)
SELECT aliases	Not allowed in MySQL or PostgreSQL	Allowed in MySQL and SQLite, not in PostgreSQL

If you remember one rule, make it this: if the condition mentions an aggregate, it goes in HAVING. Otherwise, it goes in WHERE.

The sample table I used

Every example uses the same ten orders from four customers. It's small enough to check the answers by hand:

CREATE TABLE orders (
  id       INT PRIMARY KEY,
  customer VARCHAR(20) NOT NULL,
  city     VARCHAR(20) NOT NULL,
  status   VARCHAR(10) NOT NULL,
  amount   DECIMAL(8,2) NOT NULL
);
INSERT INTO orders VALUES
 (1, 'Ana',  'London', 'paid',     60.00),
 (2, 'Ana',  'London', 'paid',     55.00),
 (3, 'Ana',  'London', 'refunded', 40.00),
 (4, 'Ben',  'Leeds',  'paid',    120.00),
 (5, 'Ben',  'Leeds',  'pending',  30.00),
 (6, 'Cara', 'London', 'pending',  25.00),
 (7, 'Cara', 'London', 'pending',  15.00),
 (8, 'Dev',  'Leeds',  'paid',     20.00),
 (9, 'Dev',  'Leeds',  'paid',     35.00),
 (10,'Dev',  'Leeds',  'paid',     10.00);

I show MySQL's output in most places. PostgreSQL and SQLite returned the same rows unless I say otherwise. SQLite prints 155 where the others print 155.00, because it doesn't keep DECIMAL scale. If joins are still fuzzy for you, my guide to INNER vs LEFT vs RIGHT vs FULL OUTER JOIN uses a similar shop table.

Where each clause runs in a query

You write SQL in one order, but the database evaluates it in another. This logical order explains almost every WHERE vs HAVING question:

FROM and JOINs pick the source rows.
WHERE throws away rows that fail the condition.
GROUP BY collects the surviving rows into groups.
Aggregates such as SUM() and COUNT() are calculated per group.
HAVING throws away groups that fail the condition.
SELECT computes the output columns and aliases.
ORDER BY sorts, then LIMIT trims.

Because WHERE runs before step 4, no totals exist yet when it runs, so it can't test them. HAVING runs after step 4, so it can. The PostgreSQL tutorial on aggregate functions walks through the same idea. Real query planners can reorder work for speed, but they must return the same result as this logical order.

WHERE: filter individual rows

WHERE checks each row on its own. Here it keeps paid orders worth at least 50:

SELECT id, customer, status, amount
FROM orders
WHERE status = 'paid' AND amount >= 50
ORDER BY id;

+----+----------+--------+--------+
| id | customer | status | amount |
+----+----------+--------+--------+
|  1 | Ana      | paid   |  60.00 |
|  2 | Ana      | paid   |  55.00 |
|  4 | Ben      | paid   | 120.00 |
+----+----------+--------+--------+

No grouping is involved. Each of the ten rows passes or fails by itself, and three pass. WHERE is also the clause you use in UPDATE and DELETE, where HAVING isn't allowed at all.

HAVING: filter groups using aggregates

Now say you want customers who have spent more than 100 in total. That condition is about a group of rows, so it belongs in HAVING:

SELECT customer, COUNT(*) AS orders, SUM(amount) AS total
FROM orders
GROUP BY customer
HAVING SUM(amount) > 100
ORDER BY customer;

+----------+--------+--------+
| customer | orders | total  |
+----------+--------+--------+
| Ana      |      3 | 155.00 |
| Ben      |      2 | 150.00 |
+----------+--------+--------+

GROUP BY made four groups (Ana, Ben, Cara and Dev). HAVING kept the two whose total is over 100. Cara (40.00) and Dev (65.00) were removed as whole groups.

HAVING can combine several aggregate conditions, and they don't have to appear in the SELECT list:

SELECT customer, COUNT(DISTINCT status) AS statuses, MAX(amount) AS biggest
FROM orders
GROUP BY customer
HAVING COUNT(DISTINCT status) > 1 AND MAX(amount) >= 50
ORDER BY customer;

| Ana      |        2 |   60.00 |
| Ben      |        2 |  120.00 |

The most common real use of HAVING COUNT(*) > 1 is finding duplicates. I use it that way in how to delete duplicate rows in MySQL but keep one.

Why WHERE SUM(...) fails: the errors in MySQL, PostgreSQL and SQLite

Put an aggregate in WHERE and all three databases refuse to run the query. This is the exact query:

SELECT customer, SUM(amount) AS total
FROM orders
WHERE SUM(amount) > 100
GROUP BY customer;

And these are the three errors:

ERROR 1111 (HY000) at line 1: Invalid use of group function

ERROR:  aggregate functions are not allowed in WHERE
LINE 3: WHERE SUM(amount) > 100

Parse error near line 1: misuse of aggregate: SUM()

That's MySQL, PostgreSQL and SQLite in order. MySQL's "Invalid use of group function" is the least obvious of the three, but it means the same thing. Fix: move the aggregate condition into HAVING, as in the previous section. The MySQL SELECT documentation says plainly that WHERE can use any function except aggregate (group) functions.

Using WHERE and HAVING together

The two clauses work well as a team. WHERE trims the rows first, then HAVING judges the groups that are left. This query asks: which customers have at least two paid orders?

SELECT customer, COUNT(*) AS paid_orders, SUM(amount) AS paid_total
FROM orders
WHERE status = 'paid'
GROUP BY customer
HAVING COUNT(*) >= 2
ORDER BY customer;

+----------+-------------+------------+
| customer | paid_orders | paid_total |
+----------+-------------+------------+
| Ana      |           2 |     115.00 |
| Dev      |           3 |      65.00 |
+----------+-------------+------------+

Compare that with the same HAVING but no WHERE. Now every customer qualifies, because everyone has at least two orders of some kind:

| Ana      |          3 |    155.00 |
| Ben      |          2 |    150.00 |
| Cara     |          2 |     40.00 |
| Dev      |          3 |     65.00 |

Ben drops out of the first query because WHERE removed his pending order before counting, which left him one paid order. Ana's total falls from 155.00 to 115.00 because her refunded order was removed. Where you put a condition changes the numbers, not just which rows appear.

The trap: WHERE removes groups you wanted to keep

Here's a mistake I see in dashboards all the time. You want the number of paid orders for every customer, so you filter with WHERE:

SELECT customer, COUNT(*) AS paid_orders
FROM orders
WHERE status = 'paid'
GROUP BY customer
ORDER BY customer;

| Ana      |           2 |
| Ben      |           1 |
| Dev      |           3 |

Cara has vanished. She has no paid orders, so WHERE removed all her rows and there was nothing left to group. You wanted to see "Cara: 0". Fix: keep all rows and count conditionally inside the aggregate:

SELECT customer,
       SUM(CASE WHEN status = 'paid' THEN 1 ELSE 0 END) AS paid_orders,
       COUNT(*) AS all_orders
FROM orders
GROUP BY customer
ORDER BY customer;

| Ana      |           2 |          3 |
| Ben      |           1 |          2 |
| Cara     |           0 |          2 |
| Dev      |           3 |          3 |

PostgreSQL and SQLite also support the standard FILTER clause, COUNT(*) FILTER (WHERE status = 'paid'), which gave the same four rows. MySQL 8.4.8 doesn't support it and returned ERROR 1064 (42000), a syntax error, so use the CASE version if your code has to run on MySQL. SQLite documents FILTER on its aggregate functions page.

Non-aggregate conditions: same result, different cost

You can put a plain column condition in HAVING, as long as that column is in the GROUP BY. These two queries returned the identical result in all three databases:

SELECT city, COUNT(*) AS orders
FROM orders
GROUP BY city
HAVING city = 'London';

SELECT city, COUNT(*) AS orders
FROM orders
WHERE city = 'London'
GROUP BY city;

| London |      5 |

So does it matter which one you use? To find out, I loaded a 100,000-row table with 1,000 customers and an index on customer_id, then compared the query plans for WHERE customer_id = 42 and HAVING customer_id = 42. Both queries returned a total of 9400. This is MySQL's plan for the WHERE version:

-> Group aggregate: sum(big_orders.amount)  (cost=45 rows=1)
    -> Index lookup on big_orders using idx_big_customer (customer_id=42)  (cost=35 rows=100)

And this is the plan for the HAVING version:

-> Filter: (big_orders.customer_id = 42)  (cost=20076 rows=982)
    -> Group aggregate: sum(big_orders.amount)  (cost=20076 rows=982)
        -> Index scan on big_orders using idx_big_customer  (cost=10066 rows=100098)

With WHERE, MySQL looked up about 100 rows through the index. With HAVING, it scanned the whole index (about 100,000 rows), built every customer's total, then threw away all but one. The estimated cost went from 45 to 20076. The MySQL manual warns about this directly: HAVING is applied nearly last, "with no optimization", and you shouldn't use it for items that belong in WHERE.

PostgreSQL 17 and SQLite were smarter. Both moved the condition down and used the index for either version:

         ->  Bitmap Index Scan on idx_big_customer
               Index Cond: (customer_id = 42)

`--SEARCH big_orders USING INDEX idx_big_customer (customer_id=?)

You can't count on that, though, so the safe habit is the same everywhere: plain column conditions go in WHERE. You can check your own queries with EXPLAIN.

HAVING on a column that is not grouped

What happens if HAVING uses a column that is neither grouped nor aggregated? Here I group by customer but filter on status:

SELECT customer, SUM(amount) AS total
FROM orders
GROUP BY customer
HAVING status = 'paid';

ERROR 1054 (42S22) at line 1: Unknown column 'status' in 'having clause'

ERROR:  column "orders.status" must appear in the GROUP BY clause or be used in an aggregate function

MySQL and PostgreSQL both reject it, which is the right call, because a group like Ana's contains both paid and refunded orders. SQLite, however, ran it and returned three rows:

| Ana      | 155   |
| Ben      | 150   |
| Dev      | 65    |

That's a silent wrong answer. Ana's total of 155 includes a refunded order, and Ben's includes a pending one. The SQLite SELECT docs explain why: a non-aggregate HAVING expression is evaluated against an arbitrarily selected row from each group. If you meant "only paid orders", that condition belongs in WHERE.

Can you use a column alias in WHERE or HAVING?

Aliases are where the three databases disagree most. I tested a SELECT alias in HAVING (HAVING total > 100, where total is SUM(amount)) and in WHERE (WHERE with_vat > 100, where with_vat is amount * 1.2):

Database	Alias in HAVING	Alias in WHERE
MySQL 8.4.8	Works	Error 1054: Unknown column 'with_vat' in 'where clause'
PostgreSQL 17.11	Error: column "total" does not exist	Error: column "with_vat" does not exist
SQLite 3.46.1	Works	Works

ERROR:  column "total" does not exist
LINE 4: HAVING total > 100

That's PostgreSQL's documented behaviour: output column names work in ORDER BY and GROUP BY, but not in WHERE or HAVING. The portable fix is to repeat the expression (HAVING SUM(amount) > 100), or to compute it in a CTE and filter it with WHERE outside:

WITH totals AS (
  SELECT customer, SUM(amount) AS total
  FROM orders
  GROUP BY customer
)
SELECT customer, total
FROM totals
WHERE total > 100
ORDER BY customer;

| Ana      | 155.00 |
| Ben      | 150.00 |

That CTE ran unchanged on all three databases. When you build these filters from user input in PHP, pass the values as placeholders, as shown in my PDO prepared statements guide, whether the condition sits in WHERE or HAVING.

HAVING without GROUP BY

HAVING without GROUP BY treats the whole filtered result as one group. With an aggregate, all three databases agree:

SELECT COUNT(*) AS paid_orders
FROM orders
WHERE status = 'paid'
HAVING COUNT(*) > 3;

|           6 |

The PostgreSQL docs note that a query like this returns one row when the HAVING condition is true and zero rows when it isn't. Things split when there's no aggregate at all, as in SELECT id, amount FROM orders HAVING amount > 100. MySQL treats it like a WHERE and returns order 4. The other two refuse:

ERROR:  column "orders.id" must appear in the GROUP BY clause or be used in an aggregate function

Parse error near line 1: HAVING clause on a non-aggregate query

That's PostgreSQL first, then SQLite. Code that relies on MySQL's leniency here will break if you ever move databases.

Quick rules for choosing

Condition on a plain column (status, city, a date)? Use WHERE.
Condition on SUM(), COUNT(), AVG(), MIN() or MAX()? Use HAVING.
Need groups with zero matches to stay visible? Don't filter them out with WHERE. Count conditionally with CASE, or FILTER outside MySQL.
Writing portable SQL? Repeat the aggregate in HAVING rather than using its alias, or use a CTE.
Not sure? Run EXPLAIN and check that your WHERE condition uses an index.

I keep a set of small browser-based helpers for everyday developer jobs on my free tools page, if you need to tidy test data before importing it.

Frequently asked questions

What is the main difference between WHERE and HAVING in SQL?

WHERE filters individual rows before they are grouped, and HAVING filters groups after GROUP BY and aggregation. That's why HAVING can test SUM(), COUNT() and other aggregates, while WHERE can't.

Can I use HAVING without GROUP BY?

Yes. The whole filtered result then counts as one group, so a query like SELECT COUNT(*) FROM orders HAVING COUNT(*) > 3 returns one row or none. A HAVING with no aggregate at all works in MySQL but fails in PostgreSQL and SQLite.

Why can't I use COUNT() or SUM() in a WHERE clause?

WHERE runs before rows are grouped, so the totals don't exist yet. MySQL reports Invalid use of group function, PostgreSQL reports aggregate functions are not allowed in WHERE, and SQLite reports misuse of aggregate. Move the condition to HAVING.

Is HAVING slower than WHERE?

It can be. In my MySQL 8.4.8 test, a plain column condition in HAVING scanned all 100,000 rows, while the same condition in WHERE read about 100 through an index. PostgreSQL 17 and SQLite optimised both forms the same way, but WHERE is the safe choice everywhere.

Which runs first, WHERE or HAVING?

WHERE runs first. The logical order is FROM, WHERE, GROUP BY, aggregates, HAVING, SELECT, then ORDER BY and LIMIT.

Can I use a column alias in HAVING?

In MySQL and SQLite, yes. In PostgreSQL, no: it reports that the column does not exist. Repeat the expression, for example HAVING SUM(amount) > 100, or wrap the query in a CTE if you need portable SQL.

Can I use both WHERE and HAVING in the same query?

Yes, and it's common. WHERE removes unwanted rows first, then HAVING filters the groups that are left. Keep in mind that the WHERE condition changes what gets counted and summed.

Last checked: 4 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.

Originally published on mfaysal.com.

I'm learning cybersecurity on TryHackMe — follow my progress at tryhackme.com/p/mfaysal.dev.

DEV Community: Mahir Faysal

TypeError: unhashable type: 'list' in Python: 10 Causes and Fixes for Dict Keys, Sets, Counter and lru_cache (Tested Examples)

What "unhashable type: 'list'" actually means

Cause 1: Using a list as a dictionary key

Cause 2: Putting lists inside a set literal

Cause 3: Calling set.add() with a list

Cause 4: Removing duplicates with set() on a list of lists

Cause 5: An in check against a set or dict

Cause 6: Counter, dict.fromkeys and groupby-style counting

Cause 7: A tuple that contains a list

Cause 8: Passing a list to an @lru_cache or @cache function

Cause 9: unhashable type: 'dict', 'set' and 'bytearray'

Cause 10: A @dataclass instance in a set or as a key

Python 3.14 changed the error message

Why Python will not let you hash a list anyway

Quick fix table for every cause

How to find the list that caused it

Frequently asked questions

How do I fix TypeError: unhashable type: 'list'?

Why are lists unhashable in Python?

Can a tuple be unhashable?

What does 'cannot use list as a dict key' mean?

How do I remove duplicate lists from a list?

How do I use lru_cache with a list argument?

How do I make a dataclass hashable?

Python Assignment vs Shallow Copy vs Deep Copy (copy vs deepcopy): Differences, Nested Lists and When to Use Each (Tested Examples)

Assignment: two names, one object

Shallow copy: a new box with the same contents

Shallow copies of lists: slicing, list() and copy()

Deep copy: copy.deepcopy copies everything inside

Assignment vs shallow copy vs deep copy compared

The [[0] * 3] * 3 trap

Copying class instances

When deepcopy fails, and how __deepcopy__ fixes it

Shared references and self-referencing lists

Tuples, strings and other immutables

The bug you get without copying: functions that change their arguments

copy.replace() in Python 3.13: copy with changes

deepcopy vs a JSON round trip

How fast is each one?

Which one should you use?

Frequently asked questions

What is the difference between copy and deepcopy in Python?

Does b = a copy a list in Python?

Is list.copy() a deep copy?

Why does changing one row change every row in my 2D list?

Why does deepcopy fail with cannot pickle _thread.lock object?

Is deepcopy slow?

Can I use json.loads(json.dumps(x)) instead of deepcopy?

Type 'X' is not assignable to type 'Y' in TypeScript (TS2322, TS2345): 10 Causes and Fixes (Tested Examples)

What the error looks like

Why TypeScript refuses the assignment

TypeScript 7 made this error more common

The 10 causes at a glance

1. An optional property or parameter (string | undefined)

2. A string from a form or URL passed where a number is expected

3. A plain string where a literal union is expected

4. A required property is missing from an object

5. A DOM query that can return null

6. Forgetting to await a Promise

7. An array with mixed types

8. A readonly array passed to a function that expects a mutable one

9. React useState(null) without a type

10. Returning a concrete value from a generic function

The fixes in one file, compiled and run

Why "as" is the wrong first fix (and satisfies is better)

How to fix it fast: a checklist

Frequently asked questions

What does Type 'X' is not assignable to type 'Y' mean?

What is the difference between TS2322 and TS2345?

How do I fix string | undefined is not assignable to type string?

Why did these errors appear after upgrading to TypeScript 7?

Is it OK to fix the error with as or any?

Why does useState(null) cause not assignable errors in React?

git fetch vs git pull (vs git pull --rebase): Differences, Divergent Branches and When to Use Each (Tested Examples)

What git fetch actually changes

Integrating after a fetch

What git pull does in one step

"fatal: Need to specify how to reconcile divergent branches"

git pull --ff-only: refuse anything but a fast-forward

When deepcopy fails, and how deepcopy fixes it