Debug Flux Source Not Ready Errors (2026)

The Flux controller is failing to reconcile your Kubernetes resources because the source controller can’t find the specified Git repository.

Common Causes and Fixes for `SourceNotReady` Errors

This error typically means the Flux Source Controller is unable to fetch artifacts from your configured source (e.g., a Git repository). Here’s a breakdown of the most common reasons and how to fix them:

Incorrect Git Repository URL:
- Diagnosis: Check the GitRepository or HelmRepository custom resource definition (CRD) that Flux is trying to use. Look for the spec.url field.
```
kubectl -n flux-system get gitrepository <your-repo-name> -o yaml
```
  Compare this URL to the actual URL of your Git repository. Common mistakes include typos, missing .git suffix for some Git hosting providers, or using SSH URLs when an HTTPS URL is expected (or vice versa).
- Fix: Edit the GitRepository CRD and correct the spec.url.
```
# Example correction for a GitRepository
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-git-repo
  namespace: flux-system
spec:
  interval: 1m
  url: "https://github.com/my-org/my-repo.git" # Corrected URL
  ref:
    branch: main
```
- Why it works: The Source Controller uses this URL to clone or fetch from your Git provider. An incorrect URL means it can’t establish a connection.
Authentication/Authorization Issues (SSH Keys or Tokens):
- Diagnosis: If your repository is private, the Source Controller needs credentials.
  - For SSH: Ensure the Secret referenced in spec.secretRef.name contains a valid identity key with the private SSH key. Also, verify the known_hosts entry in the secret is correct for your Git host.
```
kubectl -n flux-system get secret <your-secret-name> -o yaml
```
    Look for identity and known_hosts keys.
  - For HTTPS: If using a token, ensure the Secret contains a username and password (which is your token).
```
kubectl -n flux-system get secret <your-secret-name> -o yaml
```
    Look for username and password keys.
  - Check the Source Controller logs for specific authentication errors.
```
kubectl -n flux-system logs -l app=source-controller -c manager
```
- Fix:
  - SSH:
    - Generate a new SSH key pair if needed: ssh-keygen -t ed25519 -C "fluxcd@example.com"
    - Add the public key to your Git provider (e.g., GitHub Deploy Keys, GitLab Deploy Tokens).
    - Create or update the Kubernetes Secret with the private key and known_hosts entry.
```
kubectl -n flux-system create secret generic git-creds \
  --from-file=identity=~/.ssh/id_ed25519 \
  --from-literal=known_hosts='github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...'
```
    - Update your GitRepository CRD to reference this secret:
```
spec:
  url: "git@github.com:my-org/my-repo.git"
  secretRef:
    name: git-creds
```
  - HTTPS:
    - Generate a Personal Access Token (PAT) on your Git provider with appropriate read permissions.
    - Create or update the Kubernetes Secret with your username and the PAT.
```
kubectl -n flux-system create secret generic git-creds \
  --from-literal=username='my-git-username' \
  --from-literal=password='my-personal-access-token'
```
    - Update your GitRepository CRD to reference this secret:
```
spec:
  url: "https://github.com/my-org/my-repo.git"
  secretRef:
    name: git-creds
```
- Why it works: The Source Controller needs valid credentials to authenticate with your Git provider for private repositories. Without them, it’s like trying to log into a website without a password.
Network Connectivity Issues:
- Diagnosis: The Source Controller pod needs to be able to reach your Git repository URL over the network.
  - Exec into the source-controller pod:
```
kubectl -n flux-system exec -it <source-controller-pod-name> -- /bin/sh
```
  - Inside the pod, try to ping or curl the Git repository host.
```
# Example using curl (install curl if not present: apt update && apt install curl)
curl -v https://github.com
```
  - Check your Kubernetes cluster’s network policies, firewalls, or egress rules that might be blocking outbound connections from the flux-system namespace or the source-controller pod.
- Fix: Adjust network policies, firewall rules, or proxy configurations to allow the source-controller pod to connect to your Git host. If using a proxy, configure it in the Source Controller’s deployment.
- Why it works: The Source Controller cannot fetch code if it can’t establish a network connection to the remote Git server.
Incorrect Branch, Tag, or Commit SHA:
- Diagnosis: Verify that the ref specified in your GitRepository (e.g., branch: main, tag: v1.0.0, commit: abcdef123) actually exists in your Git repository.
```
# From your local machine, check if the ref exists
git ls-remote origin main # For branch
git ls-remote origin v1.0.0 # For tag
```
- Fix: Update the spec.ref in your GitRepository CRD to point to a valid and existing branch, tag, or commit SHA.
```
spec:
  interval: 1m
  url: "https://github.com/my-org/my-repo.git"
  ref:
    branch: develop # Changed to a valid branch
```
- Why it works: The Source Controller needs a valid reference point within the Git history to fetch from. An invalid ref means there’s nothing for it to retrieve.
Rate Limiting by Git Provider:
- Diagnosis: If you’re hitting your Git provider’s API rate limits (especially common with HTTPS/token authentication), the Source Controller may be temporarily blocked from fetching. Check the Source Controller logs for messages indicating rate limiting or excessive requests.
```
kubectl -n flux-system logs -l app=source-controller -c manager
```
- Fix:
  - Increase the interval in your GitRepository CRD to poll less frequently (e.g., from 1m to 5m or 10m).
```
spec:
  interval: 5m # Increased interval
  url: "https://github.com/my-org/my-repo.git"
  # ...
```
  - If using SSH, it’s generally less prone to rate limiting than token-based HTTPS.
  - Consider using a dedicated deploy key (SSH) for Flux instead of a personal access token if you’re experiencing frequent rate limiting.
- Why it works: Reducing the frequency of requests to the Git provider helps you stay within their API usage limits, preventing temporary blocks.
Git Repository Not Found (404) or Private Repository Access Denied:
- Diagnosis: This is a more direct error from the Git provider. The Source Controller logs will usually show an HTTP 404 or 403 error.
```
kubectl -n flux-system logs -l app=source-controller -c manager
```
  Look for messages like fatal: repository '...' not found or Permission denied (publickey).
- Fix: This is often a combination of points 1 and 2.
  - Ensure the URL is correct and the repository exists.
  - Ensure the credentials (SSH key or token) have the correct permissions and are associated with an account that has access to the repository.
  - For private repositories, ensure the correct SSH key is added to the Git provider’s deploy keys or the user account, or that the PAT has the necessary scopes.
- Why it works: The Git provider is explicitly denying access, either because the repository doesn’t exist at that URL or the provided credentials lack the necessary permissions.

After resolving these issues, the Source Controller should be able to fetch artifacts successfully. The next error you might encounter is if the Kustomize Controller or Helm Controller cannot apply the fetched manifests due to validation errors or other Kubernetes-specific problems.

Common Causes and Fixes for SourceNotReady Errors

Common Causes and Fixes for `SourceNotReady` Errors