KhueApps
Home/DevOps/Fix remote: Repository not found on GitHub and GitLab

Fix remote: Repository not found on GitHub and GitLab

Last updated: October 06, 2025

Table of Contents

  1. Overview
  2. Quickstart (TL;DR)
  3. Common Causes and Fixes
  4. Minimal Working Example (MWE)
  5. Step-by-Step Diagnosis
  6. Quick Troubleshooting Matrix
  7. Pitfalls
  8. Performance Notes
  9. FAQ

Overview

This guide shows practical ways to diagnose and fix the Git error:

remote: Repository not found fatal: repository '...' not found

It applies to GitHub and GitLab, via HTTPS or SSH, and covers remotes, permissions, credentials, SSH keys, and renamed projects.

Quickstart (TL;DR)

  1. Check remote URL:
    • git remote -v
    • Ensure host, owner/group, and repo path are correct and exist.
  2. Confirm access:
    • HTTPS: use a Personal Access Token (PAT) instead of a password (2FA requires PAT).
    • SSH: ensure the correct public key is added to the right account and the agent loads it.
  3. Test connectivity:
  4. Fix and retry:
    • Update remote: git remote set-url origin NEW_URL
    • Clear bad cached credentials; re-authenticate.

Common Causes and Fixes

  • Wrong remote URL (typo, wrong host, wrong path)
    • Use git remote -v and compare to the exact URL on GitHub/GitLab.
  • Missing permissions (private repo, not added as collaborator/member)
    • Request access or use the correct account.
  • Using password over HTTPS when 2FA is enabled
    • Use a PAT with the right scopes.
  • Wrong SSH key or wrong account
    • Ensure the key in your agent matches the key added to your GitHub/GitLab account.
  • Repository renamed, transferred, or deleted
    • Update the remote to the new path.
  • Submodule URLs out of date
    • Update .gitmodules and run git submodule sync.
  • Cached credentials mismatch (wrong username/token)
    • Erase/re-enter credentials via your credential helper.

Minimal Working Example (MWE)

The following sequences verify connectivity and set a correct remote. Replace OWNER/REPO or GROUP/PROJECT with real values.

SSH (GitHub):

# 1) Verify SSH can authenticate to GitHub
ssh -T [email protected]  # Expect a greeting with your username

# 2) Set a correct SSH remote and test
git remote set-url origin [email protected]:OWNER/REPO.git
# Quick, no-fetch check of remote existence
git ls-remote --heads origin

SSH (GitLab):

ssh -T [email protected]
git remote set-url origin [email protected]:GROUP/PROJECT.git
git ls-remote --heads origin

HTTPS with PAT (GitHub example using env var; avoid storing tokens in history):

export GH_USER="your-username"
export GH_PAT="your-token-with-repourl-scope"
# One-off check (note: command line will expose args in shell history)
git ls-remote "https://${GH_USER}:${GH_PAT}@github.com/OWNER/REPO.git"
# Set remote to clean URL; allow credential helper to store token on next auth
git remote set-url origin https://github.com/OWNER/REPO.git

HTTPS with PAT (GitLab):

export GL_USER="your-username"
export GL_PAT="your-token-with-api-or-read_repo-scope"
git ls-remote "https://${GL_USER}:${GL_PAT}@gitlab.com/GROUP/PROJECT.git"
git remote set-url origin https://gitlab.com/GROUP/PROJECT.git

Step-by-Step Diagnosis

  1. Inspect the current remote
git remote -v
git config --get remote.origin.url
  • Confirm the host (github.com or gitlab.com).
  • Check owner/group and repo path. For GitLab, ensure the group and subgroup path is correct.
  1. Verify the repository exists and path accuracy
  • Copy the exact clone URL from the platform.
  • Update the remote if wrong:
git remote set-url origin [email protected]:OWNER/REPO.git
# or
git remote set-url origin https://github.com/OWNER/REPO.git
  1. Test access without fetching everything
# SSH form
git ls-remote origin
# Direct URL form
git ls-remote [email protected]:OWNER/REPO.git

If this fails with “Repository not found,” your URL or credentials are still wrong.

  1. Fix HTTPS authentication
  • Use PAT, not your password (especially with 2FA).
  • Ensure PAT scopes:
    • GitHub: repo (private), or public_repo for publics; workflow if needed.
    • GitLab: read_api/read_repository or write_repository for push.
  • Clear stale credentials and retry to be prompted:
# Clear global helper (will prompt next time)
git config --global --unset credential.helper || true
# Or switch to a platform helper you use (examples):
# macOS Keychain
git config --global credential.helper osxkeychain
# Git Credential Manager
# git config --global credential.helper manager
  1. Fix SSH authentication
  • Ensure the right key is loaded:
ssh-add -l  # List keys in agent
ssh-add ~/.ssh/id_ed25519  # or your specific key
  • Test host auth:
ssh -T [email protected]
ssh -T [email protected]
  • If you must force a specific key per host, use an SSH config:
# ~/.ssh/config
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_gitlab
  IdentitiesOnly yes
  1. Handle renamed, transferred, or forked repos
  • If the repository moved, update the remote URL:
git remote set-url origin [email protected]:NEWOWNER/NEWREPO.git
  • For forks under a different namespace (GitLab group), ensure the correct group path is used.
  1. Submodules
  • Update stale submodule URLs and sync:
git config -f .gitmodules submodule.<name>.url [email protected]:OWNER/REPO.git
git submodule sync --recursive

Quick Troubleshooting Matrix

  • Symptom: Works over SSH, fails over HTTPS
    • Likely: Using password instead of PAT
    • Fix: Create PAT with proper scopes; re-authenticate
  • Symptom: Fails on CI, works locally
    • Likely: Missing deploy key or token scope in CI
    • Fix: Add read/write deploy key or CI variable PAT/token
  • Symptom: Only some users fail
    • Likely: Missing team/group membership
    • Fix: Add user to repo/team or adjust group permissions
  • Symptom: Push fails, clone succeeds
    • Likely: Read-only token/key
    • Fix: Use write-enabled PAT/key or SSH key with write access

Pitfalls

  • Embedding tokens in URLs leaks secrets in shell history and logs. Prefer credential helpers or environment-injected tokens in CI.
  • Mixing GitHub and GitLab hosts in remotes when mirroring repos. Verify origin and upstream differ correctly.
  • Incorrect case or missing subgroup for GitLab paths. Copy the exact clone URL.
  • Multiple SSH keys: the agent might send the wrong one unless you pin it in ~/.ssh/config.
  • Corporate proxies/SSL interception can mask auth errors. Verify basic ssh -T and a simple https curl if in doubt.

Performance Notes

  • Use git ls-remote to validate access quickly without a full fetch/clone.
  • For large repos, test with a shallow clone if needed:
git clone --depth=1 <url>
  • Reduce repeated failed attempts to avoid rate limits or lockouts.
  • Persist credentials via a helper to minimize extra round-trips:
git config --global credential.helper store   # plaintext; use cautiously
# or a secure helper like osxkeychain / manager

FAQ

Q: I can clone but cannot push. Why? A: Your token/key has read-only scope, or your account lacks write access. Use a PAT/key with write_repository (GitLab) or repo (GitHub) and confirm permissions.

Q: Do I need to match repo name case exactly? A: Both platforms are generally case-insensitive for paths, but copying the exact path avoids surprises, especially with nested groups.

Q: How do I verify which account my SSH key maps to? A: ssh -T [email protected] or [email protected] shows the authenticated username. Ensure it matches the account with repo access.

Q: Does 2FA block HTTPS Git operations? A: You must use a Personal Access Token instead of your password when 2FA is enabled.

Series: Git

DevOps