IndentationError: Fix Bad Indents, Tabs, and Empty Blocks

You press run and Python refuses before executing a single statement: IndentationError: unexpected indent. Nothing ran, no data changed, no logic was even evaluated — the parser rejected your file's shape. For newcomers this feels personal, as if the language is grading neatness. It isn't. Indentation is Python's grammar for grouping, doing the job braces do elsewhere, so a misaligned line genuinely changes — or destroys — the program's meaning.

This error family fires in a handful of repeatable situations. A line sits deeper than any open block, and the parser can't attach it anywhere. A dedent lands at a level no open block owns. A colon-header like if, def, or for has no body beneath it, leaving the suite empty. Or tabs and spaces mix in one file, and the parser — unable to tell which visual column a tab meant — raises TabError rather than guess.

The good news: every variant points at itself. The traceback carries a caret marking the exact line and column, and the message names the precise complaint. This article teaches you to read that caret, diagnose invisible whitespace with cat -A and tabnanny, fix each variant at the flagged line, and set up editorconfig plus ruff so your team stops shipping these entirely.

Unexpected Indent and Unindent: the Block the Parser Rejected

An unexpected indent means a line stepped right without any open block inviting it in. After a plain statement like x = 1, the parser expects the next line at the same level or a dedent — so a four-space hop on the following line has nowhere to attach, and compilation dies naming that line. The mirror image, an unexpected unindent, means a line stepped left to a level no open block owns: it left its suite but didn't land on any enclosing one. Both are shape errors, and both fire before a single statement runs.

beginners hit the first variant by pasting. A snippet copied from inside a function or a chat window carries its original leading spaces into a context one level shallower, and the pasted lines float right of everything around them. The second variant comes from deleting or misaligning a block header: the body outlives its if or for, and the orphan lines dedent into the void. In both cases the code around the error is innocent — only the flagged line's level disagrees with the structure.

The repair is mechanical. Read the caret's line and column, compare the flagged line's leading whitespace with its siblings, and move it to the level it belongs at. When the line looks correct, suspect the two lines above: a missing colon or an unclosed parenthesis changes what the parser expects, making a rightly-indented line wrong by context. Recompile with py_compile after each nudge; the loop is seconds long and always converges.

bad = "x = 1\n    y = 2\n"
try:
    compile(bad, "<demo>", "exec")
except IndentationError as exc:
    print(type(exc).__name__ + ":", exc)
    print("line:", exc.lineno, "offset:", exc.offset)

good = "x = 1\ny = 2\n"
print(compile(good, "<demo>", "exec") is not None)

Empty Suite After a Colon: if, def, and for Demand a Body

Every compound header demands a suite — at least one statement nested beneath it. When if, for, while, def, class, or with ends with a colon and nothing follows at a deeper level, the parser reports expected an indented block and stops. This isn't Python being fussy about style; a header with no body is structurally incomplete, like a bookshelf bracket with no shelf. The grammar requires the suite the way a sentence requires a verb.

You'll meet this while sketching. You write the if first intending to fill the body after lunch, or you stub three functions and implement one, or a loop's body gets deleted during an edit leaving the header behind. The whole module then refuses to import — not just your function — because compilation is all-or-nothing. One bare header poisons every test in the file, which is why this error often arrives disguised as a mysterious collection failure.

The placeholder is `pass`: a statement that does nothing and compiles to nothing, existing purely to satisfy the suite requirement. Put it under the header with a TODO comment naming the ticket, and the file imports while the work stays visibly pending. When the real body lands, the diff touches one hunk, reviewers see exactly what changed, and no other test ever noticed the gap.

def todo_later():
    pass

todo_later()
items = []
if items:
    print("has items")
else:
    pass

for i in range(3):
    if i == 1:
        pass
    print(i)
print("ok")

TabError: the Subclass That Fires on Mixed Tabs and Spaces

TabError is IndentationError's stricter child: it fires when tabs and spaces mix in a file's indentation and the parser can't determine the intended block level. A tab doesn't mean four spaces or eight — it means 'advance to the next tab stop', a width set by your editor, not your code. Two editors rendering the same file can disagree about which block a tab-indented line belongs to, so Python refuses to guess and raises instead. That refusal is a safety feature wearing an error's clothes.

The treacherous part is how innocent mixed files look. In most fonts and review tools, a tab renders at exactly the width that makes the code appear aligned — the diff looks perfect while the bytes contain two different rulers. And there's a worse outcome than the error: when the mixing is consistent enough to tokenize, the file compiles but attaches statements to the wrong block, silently changing behavior with zero visible diff. The crash is the kind outcome; silent misgrouping is the cruel one.

The remedy is uniformity enforced by tools, not eyes. Convert the file to spaces once, turn on render-whitespace so tabs glow on sight, and declare spaces in .editorconfig so every editor agrees. Because TabError subclasses IndentationError, existing except IndentationError handling already covers it — but you should never be catching this in production code. Mixed indentation is a file-construction defect, fixed at the editor and the commit hook, not at runtime.

mixed = "if True:\n    x = 1\n\tx = 2\n"
try:
    compile(mixed, "<demo>", "exec")
except TabError as exc:
    print(type(exc).__name__ + ":", exc)
    print("TabError is an IndentationError:", isinstance(exc, IndentationError))

Invisible Whitespace: Diagnose Mixed Indents With cat -A

Most indentation bugs are invisible by design: your editor renders tabs, spaces, and even non-breaking spaces as identical gaps. Diagnosis therefore means making the invisible visible. cat -A is the fastest lens — it prints tabs as ^I, marks every line end with $, and exposes non-breaking spaces as M- sequences, so a mixed-indent region shows up as ^I lines sitting among space lines. Pair it with sed -n '40,60p' to frame the neighborhood around the caret's line instead of drowning in a thousand-line dump.

The stdlib offers a second opinion: python3 -m tabnanny walks a file and reports ambiguous indentation without executing anything, which is ideal for pre-commit checks and for sweeping a whole directory after an incident. For the programmatic route, repr() on a line exposes every character honestly — tabs, trailing spaces, and exotic Unicode gaps all appear as escapes — and swapping spaces for dots makes levels countable at a glance.

Build the habit of confirming before editing. Frame the caret line with cat -A, identify the exact intruder character, fix that line, and recompile. The alternative — re-indenting whole regions by feel — usually moves the error to a new line while the original tab sits untouched two lines up. Bytes first, edits second, every time.

sample = "def f():\n    x = 1   \n\ty = 2\n"
for lineno, line in enumerate(sample.splitlines(), 1):
    stripped = line.rstrip("\n")
    if "\t" in stripped:
        print(lineno, "has TAB:", repr(stripped))
    if stripped != stripped.rstrip():
        print(lineno, "has trailing whitespace:", repr(stripped))
print("spaces shown with dots:", repr(sample.splitlines()[1]).replace(" ", "."))

.editorconfig, Ruff, and Black: Prevention That Runs Itself

Prevention beats diagnosis, and for indentation it comes in three layers that reinforce each other. The .editorconfig file declares the contract — indent_style = space, indent_size = 4, trim_trailing_whitespace = true — and every conforming editor enforces it silently as people type. No meetings, no wiki page; the file sits at the repo root and the whole team types identically from the next commit on.

The second layer is the formatter. Ruff's formatter (or Black, if that's your house standard) rewrites layout deterministically, so ruff format on save or on commit erases ragged indentation before review. The third layer is the gate: ruff check --select E,W plus ruff format --check in CI rejects any file that drifted, and a pre-commit hook runs both locally so the failure arrives in seconds on the author's machine instead of minutes into a deploy pipeline.

Teams resist this as bureaucracy until their first whitespace incident, then adopt it in an afternoon. The economics are lopsided: one CI job and one config file against crash-looped workers, rejected payments, and a rollback performed under pressure. Make the build care about whitespace and humans never have to again.

import io, tokenize


def check_indent(source):
    stack = []
    for tok in tokenize.generate_tokens(io.StringIO(source).readline):
        if tok.type == tokenize.INDENT:
            stack.append(tok.string)
            if "\t" in tok.string and " " in tok.string:
                return "mixed tabs and spaces on line " + str(tok.start[0])
    if any("\t" in s for s in stack):
        return "tabs used for indentation"
    return "indentation looks consistent"

print(check_indent("def f():\n    return 1\n"))
print(check_indent("def f():\n\treturn 1\n"))

Caret Reading: the Line and Column the Traceback Flags

The traceback for an indentation failure is unusually generous: it carries the filename, the line number, the offending line's text, and a column offset rendered as a caret. That caret marks the exact token where the parser's expectations broke — the over-indented statement, the dedent that matched nothing, the unindented line where a suite should start. Your first move is always to open that file at that line and compare its leading whitespace with the block it claims to join.

Read the message text alongside the caret. Unexpected indent means the line stepped right with no open header inviting it; expected an indented block means a colon-header above has no suite and the caret sits where the body should begin; unindent does not match any outer level means the dedent skipped past every enclosing block. Each phrase prescribes its repair: dedent the line, add the body, or re-seat the dedent at a real level.

One caution keeps this fast: the caret marks where the parser gave up, which occasionally trails the true cause. A missing colon on the line above, or an unclosed bracket two lines up, shifts the parser's expectations so a correctly indented line reads as wrong. If the flagged line looks flawless, inspect the two lines above it for unclosed syntax before touching anything else. Caret first, context second, edits last.

bad2 = "def f():\nprint('oops')\n"
try:
    compile(bad2, "<demo>", "exec")
except IndentationError as exc:
    print(type(exc).__name__ + ":", exc)
    print("file:", exc.filename, "line:", exc.lineno)
    print("offending text:", repr(exc.text))
    print("caret column:", exc.offset)
    print(" " * (exc.offset - 1) + "^")