Diagnosing and fixing a broken pre-commit configuration

Picking up the module 3 project

This module starts directly from the finished, working configuration from module 3, on my-python-script — the one that ended fully green. No other prerequisite.

The seeded defect

A very realistic typo: in .pre-commit-config.yaml, replace check-yaml with check-yml (one missing letter):

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-yml
      - id: detect-private-key
  - repo: https://github.com/psf/black
    rev: 24.10.0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/flake8
    rev: 7.1.1
    hooks:
      - id: flake8

This is the kind of mistake that happens typing fast, or copy-pasting an id from the wrong source.

The exact error

pre-commit run --all-files

Real output, obtained with pre-commit 4.6.2 on this exact configuration:

[ERROR] `check-yml` is not present in repository https://github.com/pre-commit/pre-commit-hooks.  Typo? Perhaps it is introduced in a newer version?  Often `pre-commit autoupdate` fixes this.

Exit code: 1. Notice that no hook runs at all — not even detect-private-key, black, or flake8, which were correctly configured. pre-commit validates that every declared hook-id actually exists before it launches anything: a single typo blocks the whole pass.

Diagnosing it

The message is explicit and asks the right question itself: "Typo?". The approach to follow, in order:

1. Identify which repo and which id are at fault — the message names them explicitly (check-yml, https://github.com/pre-commit/pre-commit-hooks).
2. Compare the id written in your .pre-commit-config.yaml against the real list of hooks that repo exposes — visible in its .pre-commit-hooks.yaml file at the root of the GitHub repository, where every available hook is declared with its exact id.
3. Fix the id in your local file so it matches exactly.

Never guess a "probable" id: check-yml, check_yaml, yaml-check are all plausible-looking but wrong variants. The only valid id for this hook, in this repo, is check-yaml.

Fixing it

      - id: check-yaml

Run again:

pre-commit run --all-files

Expected output — exactly the same as module 3:

check yaml...............................................................Passed
detect private key.......................................................Passed
black....................................................................Passed
flake8...................................................................Passed

Two more errors you'll run into sooner or later

No exercise to do here, but these two transcripts are real — captured under the same conditions as above — so you'll recognize them the day you actually see them.

A missing hooks field on a repo entry:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0

An error has occurred: InvalidConfigError:
==> File .pre-commit-config.yaml
==> At Config()
==> At key: repos
==> At Repository(repo='https://github.com/pre-commit/pre-commit-hooks')
=====> Missing required key: hooks

A very structured message: it literally points at the path inside the file (repos → this specific repo) and the missing field. The fix is simply to add the hooks field with at least one id.

A rev pointing to a branch instead of a tag (covered in detail in module 3): this is not a blocking error but a warning — the hooks still run on that pass, which makes this defect more insidious than an outright error, since nothing stops you from continuing to work with a configuration that isn't reproducible.

What you just did

You caused, read, and fixed a real pre-commit error — not a hypothetical one, the one the tool actually produces on this exact configuration — by following the general approach: identify the repo and id at fault, check the id actually exposed by the hooks repository, fix it, then reconfirm with pre-commit run --all-files. In the next module, you don't build on this deliberately broken configuration — you build on the working configuration from module 3, to wire it directly into a Dev Container's lifecycle.