GitHub Actions codecov/codecov-action "token required" (rate limit)

By Daniel Zoghalchali·Latchkey

Codecov allows tokenless uploads for some public repos but rate-limits them. When the limit is hit, or the repo is private, the upload fails unless a CODECOV_TOKEN is supplied.

What this error means

A codecov-action step fails to upload coverage, reporting a rate limit or that an upload token is required.

Error: Codecov: Failed to properly upload report: The process failed with exit code 1.
{"message":"Rate limit reached. Please upload with the Codecov repository upload token to resolve."}

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

Common causes

Tokenless upload rate-limited

Anonymous uploads from shared IP ranges (like GitHub-hosted runners) hit Codecov rate limits.

Private repo without a token

Private repositories require an upload token.

How to fix it

Provide CODECOV_TOKEN

1. Add the repository upload token as a secret.
2. Pass it to codecov-action via the token input.
3. Pin a major version of the action.

- uses: codecov/codecov-action@v4
  with:
    token: ${{ secrets.CODECOV_TOKEN }}

The failures that are not your workflow

• Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
• Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
• A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
• A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

How to prevent it

• Always supply CODECOV_TOKEN, even for public repos, to avoid rate limits.
• On Latchkey managed runners transient upload failures from network blips are auto-retried, but the token still resolves the rate-limit case.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions