Fixing Git error: fatal repository not found

Overview

The Git error "fatal: repository not found" usually means the remote URL is wrong or your credentials lack access. In DevOps pipelines, it also arises from missing CI secrets, SSO/policy constraints, or submodules that need their own auth.

This guide focuses on practical checks and fixes for HTTPS and SSH, local and CI environments.

Quickstart (most common fixes)

• Verify the remote URL: git remote -v
• Test anonymous reachability: git ls-remote --heads <url>
• If private repo, confirm your access (org membership, SSO, repo visibility).
• For HTTPS, use a Personal Access Token (PAT) with correct scopes.
• For SSH, add the correct public key to your account and test: ssh -T git@host.
• Fix case sensitivity: match owner/repo name exactly.

Minimal working example (HTTPS with PAT)

This example clones a private repo using an environment variable for the token, avoiding storing secrets in Git config.

#!/usr/bin/env bash
set -euo pipefail

# Inputs
echo "Usage: TOKEN=<pat> HOST=git.example.com OWNER=team REPO=service ./clone.sh"
: "${TOKEN:?missing TOKEN}"
: "${HOST:?missing HOST}"
: "${OWNER:?missing OWNER}"
: "${REPO:?missing REPO}"

# Validate repo exists and you have access (HTTP 200/401/404 behavior differs by host)
# If 404, it may not exist or you lack permission/SSO approval.

# Clone with minimal history and no submodules first
GIT_ASKPASS=/bin/echo \
  git -c credential.helper= \
  clone --depth=1 "https://x-token-auth:${TOKEN}@${HOST}/${OWNER}/${REPO}.git" "${REPO}"

cd "${REPO}"

git fetch --depth=1 origin

echo "OK: cloned ${OWNER}/${REPO}"

Notes:

• Replace x-token-auth with oauth2 or a username placeholder if your host requires it.
• Ensure the PAT includes repo/read permissions (and SSO is authorized if required).

Common causes and how to diagnose

Step-by-step fixes

1) Confirm the remote URL

1. Show configured remotes:

   git remote -v
   

2. Test reachability without credentials (public repos only):

   git ls-remote --heads https://host/owner/repo.git
   

3. If using SSH, ensure the URL matches host format:

   git@host:owner/repo.git
   

2) Fix HTTPS authentication

1. Create a PAT with the right scopes (e.g., repo read). If your org enforces SSO, authorize the token for that org.
2. Use the PAT in the URL or store it via credential helper:

   # One-off clone without storing credentials
   git -c credential.helper= clone https://<user>:<PAT>@host/owner/repo.git
   
   # Or configure helper (stores securely on your OS)
   git config --global credential.helper store    # or manager/libsecret/osxkeychain
   git clone https://host/owner/repo.git
   # When prompted, supply username and PAT as password
   

3. If prompts are blocked (CI), set environment variables and avoid echoing secrets to logs.

3) Fix SSH authentication

1. List keys and ensure the private key is readable by your agent:

   ssh-add -l || eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
   

2. Test auth to your host:

   ssh -T git@host
   

3. Make sure the public key used is uploaded to the correct account/org and not expired or restricted.
4. If multiple keys/hosts, use an SSH config:

   # ~/.ssh/config
   Host git.example.com
     HostName git.example.com
     User git
     IdentityFile ~/.ssh/id_ed25519
     IdentitiesOnly yes
   

4) Case sensitivity and exact path

• Some hosts treat Owner/Repo vs owner/repo differently via git transport.
• Copy the clone URL exactly as provided by the host; avoid trailing .git mismatches if the host requires it.

5) Submodules

1. Inspect submodule URLs:

   git config --file .gitmodules --get-regexp submodule
   

2. Align auth with the parent clone (e.g., all HTTPS with the same PAT or all SSH):

   git submodule sync --recursive
   git -c submodule.recurse=true submodule update --init --recursive
   

3. For private submodules over HTTPS, use a token-rewriting rule:

   git config --global url."https://<user>:<PAT>@host/".insteadOf "https://host/"
   

6) CI/CD specifics

• Provide tokens/keys via the pipeline’s secret store and reference them in steps.
• Ensure secrets are available for the event (fork PRs often block secrets).
• Example (generic CI with PAT):

steps:
  - run: |
      git -c credential.helper= clone https://x-token-auth:${PAT}@${HOST}/${OWNER}/${REPO}.git repo
    env:
      PAT: ${{ secrets.REPO_READ_TOKEN }}
      HOST: git.example.com
      OWNER: team
      REPO: service

Verification checklist

• git remote -v shows the correct canonical URL.
• git ls-remote <url> succeeds (for private repos, with proper auth).
• ssh -T git@host returns a greeting with your account (SSH).
• PAT scopes include repo/read and are SSO-approved if required.
• Submodules clone successfully with the same auth scheme.

Pitfalls to avoid

• Putting PATs directly in remotes that get pushed to origin. Prefer env/credential helpers.
• Mixing SSH for parent repo and HTTPS for submodules; choose one method consistently.
• Using expired or org-revoked tokens/keys.
• Forgetting to update remotes after repo/owner rename or migration.
• Corporate proxies or MITM SSL inspection breaking TLS; configure your CA bundle if needed.
• 2FA enabled but trying password over HTTPS; use a PAT instead.

Performance notes

• Use shallow clones for CI: --depth=1 and --filter=blob:none for large repos.
• Disable recursive submodules unless needed: --recurse-submodules only when required.
• Enable protocol v2 for efficiency:

  git config --global protocol.version 2
  

• Use git lfs install when the repository uses LFS; otherwise clone may fail or be slow.

Tiny FAQ

• Q: Is "repository not found" different from "permission denied"? A: Many hosts mask permission issues as 404. Treat both as potential auth problems.
• Q: Why does web UI access work but git clone fails? A: Your PAT/SSH key lacks scopes or SSO approval. Web session uses a different auth path.
• Q: Do I need .git at the end of the URL? A: Some hosts require it for Git transport. Use the clone URL provided by the host.
• Q: How do I clear bad cached credentials? A: git credential reject or clear via your OS keychain/credential manager, then retry.

Summary

Most "fatal: repository not found" errors trace to an incorrect remote URL, insufficient permissions, or misconfigured credentials. Validate the URL, test auth (HTTPS PAT or SSH key), align submodule authentication, and ensure CI secrets are correctly wired.