How to fix fatal: repository 'https://github.com/user/submodule.git/' not found in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 211 views

This error occurs when Git cannot access a submodule's remote repository during clone, update, or init operations. Common causes include the repository being deleted, renamed, made private, or authentication issues preventing access. The fix involves verifying the repository exists, updating the submodule URL, or fixing authentication credentials.

Quick fix

Fixes fatal: repository 'https://github.com/user/submodule.git/' not found

# View all submodule URLs
cat .gitmodules

# Or use git config to see the URLs
git config --file .gitmodules --get-regexp url

Verify the submodule repository exists
Check your authentication credentials
Update the submodule URL
Clean and reinitialize the submodule

git — error

$# View all submodule URLs
cat .gitmodules
# Or use git config to see the URLs
git config --file .gitmodules --get-regexp url
fatal: repository 'https://github.com/user/submodule.git/' not found

What this error means

The "fatal: repository not found" error for submodules indicates that Git cannot locate or access the remote repository specified in your project's submodule configuration. When you run `git submodule update --init`, `git clone --recurse-submodules`, or similar commands, Git attempts to fetch each submodule from its configured URL. This error typically means one of several things: - **The submodule repository no longer exists** - It may have been deleted or moved to a different location - **The repository was renamed** - GitHub and other hosts allow renaming, but old URLs may stop working after the redirect grace period - **Access permissions changed** - The repository may have been made private, or your access was revoked - **Authentication failure** - Your credentials may be invalid, expired, or not configured for this repository - **URL format issues** - The submodule URL may be malformed or use an unsupported protocol The submodule configuration is stored in two places: the `.gitmodules` file (committed to the repository) and your local `.git/config` file (local copy after `git submodule init`). Both must point to a valid, accessible repository.

Typical symptoms

git submodule update --init fails with 'fatal: repository not found'
git clone --recurse-submodules fails when fetching a specific submodule
CI/CD pipelines fail during submodule checkout
The error shows the exact submodule URL that cannot be accessed
Other submodules in the same project clone successfully
The submodule directory exists but is empty after clone
git submodule status shows a '-' prefix indicating uninitialized submodule

Common causes

The submodule repository was deleted from the remote host
The repository was renamed and the old URL no longer redirects
The repository was made private and you lack access permissions
Your SSH key or access token is not authorized for this repository
The .gitmodules file contains an incorrect or outdated URL
The submodule URL uses a different protocol (SSH vs HTTPS) than your credentials support
The repository owner changed the repository's visibility settings
Your authentication credentials have expired or been revoked
Network or firewall issues are blocking access to the repository host
The repository URL contains a typo or case sensitivity issue

How to fix "fatal: repository 'https://github.com/user/submodule.git/' not found"

1Verify the submodule repository exists

First, confirm whether the submodule repository actually exists at the specified URL.

Check the submodule URL in your project:

bash

# View all submodule URLs
cat .gitmodules

# Or use git config to see the URLs
git config --file .gitmodules --get-regexp url

Try accessing the repository directly:
- Open the URL in a web browser
- For private repositories, ensure you're logged in
- Check if the repository name matches exactly (case-sensitive on some hosts)

Test with git ls-remote:

bash

# Replace with your actual submodule URL
git ls-remote https://github.com/user/submodule.git

# If using SSH
git ls-remote git@github.com:user/submodule.git

If the repository doesn't exist, you'll need to find its new location or remove the submodule.

2Check your authentication credentials

If the repository exists but is private, verify your authentication:

For HTTPS URLs:

bash

# Check your credential helper
git config --global credential.helper

# On macOS, list stored credentials
git credential-osxkeychain get

# Test authentication with a simple clone
git clone https://github.com/user/submodule.git /tmp/test-clone

For SSH URLs:

bash

# Test SSH connection to GitHub
ssh -T git@github.com

# For GitLab
ssh -T git@gitlab.com

# For Bitbucket
ssh -T git@bitbucket.org

# List loaded SSH keys
ssh-add -l

If SSH key is not loaded:

bash

# Start ssh-agent
eval "$(ssh-agent -s)"

# Add your key
ssh-add ~/.ssh/id_rsa
# Or for newer ed25519 keys
ssh-add ~/.ssh/id_ed25519

For GitHub Personal Access Tokens:

bash

# Test with a PAT (replace YOUR_TOKEN)
git ls-remote https://YOUR_TOKEN@github.com/user/submodule.git

3Update the submodule URL

If the repository moved or you need to use a different URL format:

Update URL in .gitmodules:

bash

# Edit .gitmodules directly, or use git config
git config --file .gitmodules submodule.path/to/submodule.url https://github.com/newuser/newrepo.git

# Verify the change
cat .gitmodules

Sync the URL to your local config:

bash

# This copies URLs from .gitmodules to .git/config
git submodule sync

# For all submodules including nested ones
git submodule sync --recursive

Then update the submodule:

bash

git submodule update --init --recursive

If switching from SSH to HTTPS (or vice versa):

bash

# SSH format
git config --file .gitmodules submodule.mysubmodule.url git@github.com:user/repo.git

# HTTPS format
git config --file .gitmodules submodule.mysubmodule.url https://github.com/user/repo.git

# Sync and update
git submodule sync
git submodule update --init

Don't forget to commit the .gitmodules change if you want others to use the new URL.

4Clean and reinitialize the submodule

If the submodule state is corrupted, try a clean reinitialization:

Remove cached submodule data:

bash

# Remove the submodule from .git/modules
rm -rf .git/modules/path/to/submodule

# Remove the submodule directory
rm -rf path/to/submodule

# Deinitialize the submodule
git submodule deinit -f path/to/submodule

Reinitialize:

bash

# Initialize and update
git submodule init path/to/submodule
git submodule update path/to/submodule

# Or do both in one command
git submodule update --init path/to/submodule

For all submodules:

bash

# Nuclear option - reset all submodules
git submodule deinit --all -f
rm -rf .git/modules/*
git submodule update --init --recursive

This approach is useful when local submodule state doesn't match what's configured.

5Handle private repository access in CI/CD

In CI/CD environments, authentication for private submodules requires special handling:

For GitHub Actions:

yaml

- uses: actions/checkout@v4
  with:
    submodules: recursive
    token: ${{ secrets.PAT_TOKEN }}  # PAT with repo access

For GitLab CI:

yaml

before_script:
  - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/".insteadOf "git@gitlab.com:"
  - git submodule sync --recursive
  - git submodule update --init --recursive

For CircleCI:

yaml

- checkout
- run:
    name: Initialize submodules
    command: |
      git submodule sync
      git submodule update --init --recursive

Using deploy keys:
For private submodules, consider using deploy keys (read-only SSH keys) specific to each submodule repository.

Using .gitconfig URL rewriting:

bash

# Rewrite SSH URLs to use HTTPS with token
git config --global url."https://oauth2:${TOKEN}@github.com/".insteadOf "git@github.com:"

6Remove or replace an unavailable submodule

If the submodule repository is permanently unavailable, you may need to remove it:

Remove the submodule completely:

bash

# 1. Deinitialize the submodule
git submodule deinit -f path/to/submodule

# 2. Remove from .git/modules
rm -rf .git/modules/path/to/submodule

# 3. Remove the submodule directory
git rm -f path/to/submodule

# 4. Commit the removal
git commit -m "Remove unavailable submodule"

Replace with a fork or alternative:

bash

# After removing, add a new submodule at the same path
git submodule add https://github.com/yourfork/repo.git path/to/submodule

# Or add an alternative library
git submodule add https://github.com/alternative/repo.git path/to/submodule

git commit -m "Replace submodule with fork/alternative"

Convert submodule to regular files:
If you have a cached version of the submodule, you can convert it to regular tracked files:

bash

# If the submodule directory has content
git rm --cached path/to/submodule
rm -rf path/to/submodule/.git
git add path/to/submodule
git commit -m "Convert submodule to regular directory"

Advanced notes

Understanding Submodule URL Resolution:

Git stores submodule information in two places:
1. .gitmodules - Committed file that all clones see
2. .git/config - Local file after running git submodule init

The git submodule sync command copies URLs from .gitmodules to .git/config. If someone updates .gitmodules and you pull their changes, your local .git/config won't automatically update - you need to run git submodule sync.

Relative Submodule URLs:

Git supports relative URLs for submodules:

bash

# In .gitmodules
[submodule "lib"]
    path = lib
    url = ../other-repo.git

This is resolved relative to the parent repository's remote URL. If your parent repo is at https://github.com/org/main.git, the submodule URL becomes https://github.com/org/other-repo.git.

Relative URLs can break when:
- The parent repo is cloned with a different protocol (SSH vs HTTPS)
- The repositories are on different hosts
- The directory structure doesn't match

Branch Tracking for Submodules:

By default, submodules are pinned to a specific commit. To track a branch:

bash

# Configure submodule to track a branch
git config -f .gitmodules submodule.mysubmodule.branch main

# Update submodule to latest on that branch
git submodule update --remote mysubmodule

Shallow Submodule Clones:

To speed up cloning, use shallow submodules:

bash

git submodule update --init --depth 1

This can fail if the pinned commit is too far back in history. In that case, you'll need a deeper clone.

Debugging Submodule Issues:

bash

# Verbose output during submodule operations
GIT_TRACE=1 git submodule update --init

# Check submodule status
git submodule status

# Shows:
# - (minus) = Not initialized
# + (plus) = Checked out commit differs from index
# U = Has merge conflicts
# (space) = Properly initialized and up-to-date

Handling Nested Submodules:

Submodules can contain their own submodules. Always use --recursive:

bash

git submodule update --init --recursive
git clone --recurse-submodules repo-url

Security Considerations:

- Be cautious with submodules from untrusted sources
- Submodules can execute code through hooks during clone/update
- Review submodule repositories before adding them to your project
- Consider using specific commit SHAs rather than branch tracking for better reproducibility and security

Frequently asked questions

What does "fatal: repository 'https://github.com/user/submodule.git/' not found" mean?: The "fatal: repository not found" error for submodules indicates that Git cannot locate or access the remote repository specified in your project's submodule configuration. When you run git submodule update --init, git clone --recurse-submodules, or similar commands, Git attempts to fetch each submodule from its configured URL. git/config file (local copy after git submodule init).
How do I fix "fatal: repository 'https://github.com/user/submodule.git/' not found"?: This error occurs when Git cannot access a submodule's remote repository during clone, update, or init operations. Common causes include the repository being deleted, renamed, made private, or authentication issues preventing access. The fix involves verifying the repository exists, updating the submodule URL, or fixing authentication credentials.
What causes "fatal: repository 'https://github.com/user/submodule.git/' not found"?: The submodule repository was deleted from the remote host The repository was renamed and the old URL no longer redirects The repository was made private and you lack access permissions
Is the "fatal: repository 'https://github.com/user/submodule.git/' not found" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
Git - Submodules Documentation(Official Docs)
📖
git-submodule - Git Documentation(Official Docs)
💬
Git will not init/sync/update new submodules - Stack Overflow(Stack Overflow)
💬
Git submodule update fails: ERROR: Repository not found - CircleCI(Stack Overflow)
📖
Fix Git's 'fatal: repository not found' error quickly(Official Docs)

How to fix fatal: repository 'https://github.com/user/submodule.git/' not found in Git

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "fatal: repository 'https://github.com/user/submodule.git/' not found"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading