pre-commit hook "exceeded timeout" in CI

By Kaveh Alemi·Latchkey

A hook ran longer than its allotted time and pre-commit killed it, or the job hit the CI step timeout while pre-commit cloned hook repos and built environments on a cold cache.

What this error means

A hook stops with a timeout message, or the CI job is cancelled at the step timeout during "Installing environment for ..." because the cache was empty.

[INFO] Installing environment for https://github.com/psf/black.
[INFO] Once installed this environment will be reused.
Error: The action 'Run pre-commit' has timed out after 10 minutes.

Common causes

A cold cache rebuilds every hook environment

With no cached PRE_COMMIT_HOME, pre-commit clones each hook repo and builds each language env from scratch, which can outlast a short step timeout.

A genuinely slow hook over many files

A heavy hook (a full type check or scan) running --all-files on a large tree can exceed a hook-level or step-level timeout.

How to fix it

Cache the pre-commit environments

1. Cache ~/.cache/pre-commit keyed on the config file.
2. Reuse it across runs so environments are not rebuilt every time.
3. Raise the step or job timeout if the first cold run is still tight.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pre-commit
    key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}

Scope heavy hooks or raise the timeout

Limit an expensive hook to changed files, or increase the job timeout for the cold path.

jobs:
  lint:
    timeout-minutes: 20

How to prevent it

• Cache PRE_COMMIT_HOME so cold builds happen once.
• Keep heavy hooks scoped with files: patterns.
• Set realistic step and job timeouts for the first cold run.

Frequently asked questions

Related guides

References

• GitHub Actions documentation