How to Troubleshoot a Stale or Wrong Badge

A wrong badge is almost always a wrong branch parameter, a cached camo copy, or a mismatched workflow file name.

Work outside in: confirm the true value at the source, then rule out the branch parameter, then camo caching, then the workflow file name in the URL. Each check isolates one cause.

Checklist

• Open the badge source URL directly to see the real current value.
• Confirm the ?branch= (and ?event=) matches the branch you expect.
• Confirm the URL uses the workflow file name, not the workflow display name.
• If the source is correct but the README lags, suspect camo caching.

Diagnose from the terminal

# True value straight from the source
curl -s "https://github.com/acme/widget/actions/workflows/ci.yml/badge.svg?branch=main" | grep -o 'passing\|failing\|no status'

# What camo currently serves in the README
curl -sI "https://camo.githubusercontent.com/<hash>" | grep -i 'cache-control\|expires'

Gotchas

• A badge that reads "no status" usually means the workflow has never run on that branch or event.
• A renamed workflow file breaks the old badge URL; update the README when you rename it.

Related guides