flux GitRepository FetchFailed: authentication error in secretRef secret

The source-controller can not authenticate with the secretRef secret value the secret is missing, the token expired, or the keys are wrong (username/password for HTTPS, identity/known_hosts for SSH). Inspect the GitRepository's secretRef, verify the secret exists with exactly those keys, fix or recreate it, and flux reconcile source git [name] to retry.

The error

GitRepository [name] FetchFailed: authentication error - check secretRef

What to do

1. Find the referenced secret value ```bash

kubectl -n flux-system get gitrepository [name] -o jsonpath='{.spec.secretRef.name}{"\n"}'

   Expected: Prints the secret name.
2. Check it exists with the right keys:
```bash
kubectl -n flux-system get secret [secret] -o jsonpath='{.data}'

Expected: HTTPS needs username+password; SSH needs identity+known_hosts.

3. Fix the secret (recreate with flux create secret git, or fix the keys/format). Expected: Secret valid.

4. Retry:

flux reconcile source git [name] -n flux-system

Expected: FetchFailed clears; Ready=True.

When this applies

• GitRepository FetchFailed with authentication error
• rotated tokens that were never updated in the secret
• SSH secrets with malformed identity keys

When it does NOT apply

• repository not found (URL wrong)
• branch/tag not found (ref wrong)

Works with

flux CLI 2.x; source-controller

HelmRepository auth failures

Same secretRef shape for chart repos. Same key-check fix.

Why it happens

The controller authenticates on every fetch with the current secret contents - there is no caching of a working credential. Rotation or a malformed key breaks the next fetch, and everything downstream stalls on the last good revision.

Edge cases

• An SSH identity key in the wrong format (e.g. PuTTY) fails the same way - use OpenSSH format.
• Self-signed git servers need the caFile key in the same secret or TLS fails first.

Resolved from

gh:fluxcd/agent-skills (gitops-cluster-debug) - https://github.com/fluxcd/agent-skills/blob/HEAD/skills/gitops-cluster-debug/references/troubleshooting.md

Asked: Flux GitRepository reports FetchFailed authentication error after a token rotation. Verified answer: Verify the secretRef secret has the exact keys the URL scheme needs; reconcile to retry. Source: https://github.com/fluxcd/agent-skills/blob/HEAD/skills/gitops-cluster-debug/references/troubleshooting.md (thread gh:fluxcd/agent-skills (gitops-cluster-debug)). Tool: flux-cli.