flake8 "E999 SyntaxError" Fails the Lint Job in CI

flake8 reports E999 when it cannot even parse a file into an AST. It is not a style nit - the file is unparseable to the Python flake8 runs under, often because that interpreter is older than the syntax in the code.

What this error means

The lint job fails with E999 SyntaxError: invalid syntax (or E999 IndentationError/TabError) pointing at a line that looks valid. flake8 stops linting that file because it could not build its AST.

app/handlers.py:14:11: E999 SyntaxError: invalid syntax
    total := compute()
          ^

Common causes

flake8 runs under an older Python than the code targets

flake8 parses with the interpreter it is installed under. New syntax (walrus 3.8+, match 3.10+) raises E999 if that interpreter is older than the feature.

A genuine syntax/indentation error

A real SyntaxError, IndentationError, or TabError in the file makes it unparseable - a code fix, not a transient one.

How to fix it

Run flake8 under a Python that supports the syntax

Install flake8 into, and run it with, an interpreter new enough for the code’s features.

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
- run: python -m flake8 .

Fix a real syntax error

1. If the interpreter is already new enough, the E999 is a genuine syntax error - correct the flagged line.
2. Run python -m py_compile <file> to confirm the file parses.
3. This is not transient; it never passes on retry without a change.

How to prevent it

• Run flake8 via python -m flake8 under your target Python version.
• Add a py_compile or formatter check early to catch parse errors.
• Pin a Python version that supports every syntax feature you use.

Related guides