🚨 Linux Error: Failed to download metadata for repo — Cause, Fix, and Troubleshooting Guide

Summary

Failed to download metadata for repo '<repo>' means dnf could not fetch repodata/repomd.xml (the repository’s metadata index) from a configured repository. On RHEL/Rocky/Alma this is a connectivity, TLS, or repo-configuration problem — dnf reached for the index and got a network error, a 404, or an untrusted certificate. The fix is to prove where the request breaks (DNS, proxy, TLS, or a dead mirror URL) and correct that layer, then clean the dnf cache.

Common Symptoms

• dnf install/dnf update aborts with Error: Failed to download metadata for repo 'baseos'.
• Trailing detail: Cannot download repomd.xml, Status code: 404, or Curl error (6): Couldn't resolve host.
• Errors during downloading metadata for repository ... followed by mirror URLs.
• On end-of-life releases (e.g., CentOS 8), all mirrors return 404.
• Common on hosts behind a proxy, with wrong system time, or an unregistered RHEL subscription.

Most Likely Causes of the ‘Failed to download metadata for repo’ Error

The most common production cause is a broken or end-of-life repo URL (dead mirror, retired release, or a baseurl typo). Other causes:

• No/incorrect proxy configuration for a host that must egress through a proxy.
• TLS failure: expired CA bundle, self-signed mirror cert, or clock skew making certs look invalid.
• DNS resolution failure for the mirror host.
• RHEL system not registered/attached to a subscription, so entitled repos 404.
• Corrupt local dnf metadata cache.

Quick Triage

# Refresh cache and force a metadata re-download
sudo dnf clean all
sudo dnf makecache

# List repos and see which one fails
dnf repolist -v

# Can you even reach the repo's metadata directly?
curl -sSI https://<mirror-host>/<path>/repodata/repomd.xml

Diagnostic Commands

# Show every enabled repo with its resolved baseurl/mirrorlist
dnf repolist -v

# Inspect the repo definitions
ls -l /etc/yum.repos.d/
grep -R "baseurl\|mirrorlist\|metalink" /etc/yum.repos.d/

# Fetch the metadata index by hand — this isolates network vs dnf
curl -sSI https://<mirror-host>/<path>/repodata/repomd.xml
# TLS-specific probe
curl -vsSL https://<mirror-host>/ 2>&1 | grep -Ei 'ssl|certificate|expire'

# DNS + proxy checks
getent hosts <mirror-host>
env | grep -i proxy
grep -i proxy /etc/dnf/dnf.conf /etc/yum.conf 2>/dev/null

# Clock skew breaks TLS validation
timedatectl

A curl -sSI that succeeds while dnf fails points at cache or proxy config; a curl that also fails points at network/TLS/URL.

Fix / Remediation

1. Clean the cache and rebuild (safest, fixes stale metadata):

   sudo dnf clean all
   sudo rm -rf /var/cache/dnf
   sudo dnf makecache

2. Fix the repo URL for a dead mirror or EOL release. Edit the file in /etc/yum.repos.d/ to a working baseurl (for archived releases, point at the vault):

   sudo sed -i 's|^mirrorlist=|#mirrorlist=|' /etc/yum.repos.d/<repo>.repo
   sudo sed -i 's|^#\?baseurl=.*|baseurl=https://vault.example.com/<release>/BaseOS/x86_64/os/|' \
     /etc/yum.repos.d/<repo>.repo
   sudo dnf makecache

3. Configure the proxy if the host egresses through one:

   echo 'proxy=http://proxy.corp.example:3128' | sudo tee -a /etc/dnf/dnf.conf
   sudo dnf makecache

4. Fix TLS/clock issues: update the CA bundle and correct the time so certificates validate.

   sudo dnf install -y ca-certificates || true
   sudo update-ca-trust
   sudo timedatectl set-ntp true

5. Register the RHEL subscription if entitled repos 404:

   sudo subscription-manager register
   sudo subscription-manager attach --auto
   sudo dnf repolist

6. Temporarily skip a single broken repo to unblock other work (not a permanent fix):

   sudo dnf --disablerepo='<repo>' install <pkg>

Warning: Do not paper over a TLS error with sslverify=false in the repo file. A failing certificate can mean a MITM proxy or an expired CA — fix the trust chain and clock instead of disabling verification.

Validation

# Metadata now downloads and repolist is clean
sudo dnf makecache
dnf repolist

# The metadata index is reachable and returns 200
curl -sSI https://<mirror-host>/<path>/repodata/repomd.xml | head -1

# A real install/upgrade succeeds
sudo dnf -y check-update || true

Prevention

• Pin repos to stable, supported baseurls; watch for end-of-life releases and migrate to the vault promptly.
• Keep the CA bundle current (ca-certificates) and enforce NTP so TLS validation never fails on clock skew.
• Manage proxy settings centrally in /etc/dnf/dnf.conf and monitor proxy/mirror availability.
• Keep RHEL subscriptions attached and alert before entitlements lapse.
• On Debian/Ubuntu the equivalent failure is apt’s Failed to fetch ... Could not resolve/connect; the same DNS, proxy, TLS, and URL causes apply — cross-check /etc/apt/sources.list the way you would /etc/yum.repos.d/.

Related Errors

• Hash Sum mismatch
• NO_PUBKEY / the following signatures couldn’t be verified
• Temporary failure in name resolution
• Connection timed out
• rpmdb BDB0113 thread/process failed

Final Notes

Treat Failed to download metadata for repo as a layered problem: isolate whether the break is DNS, proxy, TLS, clock, or a dead URL with a manual curl to repomd.xml, then fix that layer and rebuild the cache. Never disable TLS verification to move on — correct the certificate, time, and repo URL so metadata stays trustworthy.

Want faster Linux incident response? Use DevOps AI Toolkit to turn production errors into clear diagnostics, remediation steps, and reusable runbooks.