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

GitINTERMEDIATEMEDIUM

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 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.

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 [email protected]: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 [email protected]

# For GitLab
ssh -T [email protected]

# For Bitbucket
ssh -T [email protected]

# 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://[email protected]/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 [email protected]: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 "[email protected]:"
  - 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 "[email protected]:"

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

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading