gofmt -l lists unformatted files and fails CI

By Daniel Zoghalchali·Latchkey

gofmt -l lists files whose formatting differs from gofmt's output. A common CI gate fails the job when that list is non-empty, since it means committed code is not gofmt-formatted.

What this error means

A formatting step prints one or more file paths (from gofmt -l) and the job fails, often via test -z "$(gofmt -l .)" returning non-zero.

$ test -z "$(gofmt -l .)"
internal/server/handler.go
Error: Process completed with exit code 1.

Common causes

Files committed without gofmt

The listed files were saved without running gofmt, so they differ from its canonical formatting and gofmt -l reports them.

A formatting gate that fails on any listed file

The CI step treats non-empty gofmt -l output as a failure, which is the intended formatting enforcement.

How to fix it

Format with gofmt -w and commit

1. Run gofmt -w . (or gofmt -s -w . to simplify) across the repo.
2. Commit the formatting changes.
3. Re-run gofmt -l . and confirm it prints nothing.

gofmt -s -w .
gofmt -l .   # expect empty output

Show the exact diff in CI

Use gofmt -d to print the formatting diff so reviewers see what changed.

gofmt -d .

How to prevent it

• Enable gofmt format-on-save in your editor.
• Run gofmt -l . in a pre-commit hook.
• Keep the gofmt gate in CI to catch drift.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation