You run sudo dnf upgrade and the terminal stops
You type sudo dnf upgrade and hit enter. The terminal pauses, then prints Error: Failed to synchronize cache for repo 'fedora'. You check your browser and the internet works fine. You try again. Same error. The package manager refuses to proceed, and you cannot install, remove, or update any software until the cache synchronizes. This error blocks all DNF transactions. You need to restore the connection between DNF and the repositories to get your system moving again.
What's actually happening
DNF maintains a local cache of repository metadata in /var/cache/dnf/. This cache contains files like repomd.xml, primary.xml.gz, and modules.yaml. These files tell DNF what packages exist, what versions are available, and how dependencies resolve. When you run a command, DNF attempts to synchronize the local cache with the remote repositories. It fetches repomd.xml first, which acts as an index with checksums for all other metadata files. If the checksum matches the local copy, DNF skips downloading the rest. This optimization keeps transactions fast.
The "Failed to synchronize cache" error means DNF could not fetch or validate this metadata. The failure usually stems from three causes. A corrupted file in the local cache can cause checksum mismatches that DNF cannot resolve. A network path issue can prevent DNF from reaching the mirrorlist or the selected mirror. A configuration error in the repository definition files can point DNF to a broken URL or a disabled repository. DNF fails fast to prevent hanging your terminal while waiting for a dead server. It does not retry indefinitely.
The fix
Clear the cache and force a refresh
The most common cause is a corrupted or stale cache file. A partial write during a previous transaction can leave repomd.xml in an inconsistent state. Clearing the cache forces DNF to discard the local files and fetch fresh metadata from the servers.
Here's how to wipe the cache and rebuild it from scratch.
sudo dnf clean all
# clean all removes headers, packages, and metadata from /var/cache/dnf
# this deletes the local copy of repomd.xml and all repository data
sudo dnf makecache
# makecache forces DNF to download metadata for all enabled repositories
# this verifies that the repositories are reachable and the metadata is valid
Run sudo dnf check-update immediately after. If the error disappears and you see a list of packages, the cache was the problem. If the error persists, the issue lies with network connectivity or repository configuration.
dnf upgrade --refresh is the standard weekly maintenance command. It refreshes metadata before checking for updates. You should use this instead of just dnf upgrade once a week to avoid stale metadata surprises. Running --refresh ensures DNF fetches the latest repomd.xml even if the cache appears fresh.
Clean the cache before you blame the network. Corrupted metadata causes more failures than dead mirrors.
Test mirror connectivity
If cleaning the cache does not resolve the error, the problem is likely network-related. Fedora repositories use a mirrorlist mechanism. DNF fetches a metalink file that contains a ranked list of mirrors. DNF selects the best mirror based on priority and geographic location. If the mirrorlist URL is unreachable, or if all mirrors in the list are down, DNF cannot synchronize.
Here's how to test whether the metadata index is reachable from your system.
curl -I https://download.fedoraproject.org/pub/fedora/linux/releases/40/Everything/x86_64/os/repodata/repomd.xml
# -I fetches headers only to test reachability without downloading content
# repomd.xml is the metadata index file DNF looks for first
# a 200 OK response means the server is reachable and the file exists
If curl returns 200 OK, the network path to the main server is open. The issue might be a specific mirror timeout or a broken mirrorlist. If curl fails with Connection timed out or Could not resolve host, your system has a broader network issue. Check your DNS configuration and firewall rules.
You may see a more specific error like Error: Failed to download metadata for repo 'fedora': Cannot prepare internal mirrorlist: No URLs in mirrorlist. This error means the mirrorlist URL returned an empty list or an error response. The mirrorlist service itself might be temporarily unavailable.
Force a direct baseurl
When the mirrorlist mechanism fails, you can bypass it by pointing DNF directly to the main Fedora download server. This overrides the mirrorlist directive and uses a hardcoded baseurl. This is a temporary workaround. Hardcoding baseurl removes the load balancing and geographic optimization provided by the mirror network.
Here's how to modify the repository configuration to use the primary server directly.
[base]
name=Fedora $releasever - $basearch
# baseurl overrides mirrorlist and points directly to the primary server
# this bypasses the metalink mechanism and uses a single source
baseurl=https://download.fedoraproject.org/pub/fedora/linux/releases/$releasever/Everything/$basearch/os/
enabled=1
# enabled=1 ensures the repository is active for transactions
gpgcheck=1
Edit the file in /etc/yum.repos.d/. The exact filename depends on your Fedora version and architecture. Common files are fedora.repo, fedora-updates.repo, and fedora-modular.repo. Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The repo files are in /etc/yum.repos.d/.
After saving the file, run sudo dnf makecache again. If the synchronization succeeds, the mirrorlist was the bottleneck. Revert to mirrorlist when the issue resolves. Hardcoded baseurls break when the main server moves or throttles connections.
Revert to mirrorlist when the workaround is done. Hardcoded baseurls break when the main server moves or throttles.
Configure proxy and firewall
Corporate environments often require a proxy for outbound traffic. DNF respects proxy settings defined in /etc/dnf/dnf.conf. If your system is behind a proxy and DNF is not configured to use it, DNF will fail to reach the repositories. Similarly, a local firewall might block DNF's network access.
Here's how to add proxy configuration to the DNF configuration file.
[main]
proxy=http://your-proxy-server:port
# proxy defines the HTTP proxy DNF uses for repository connections
# replace your-proxy-server:port with your actual proxy address
proxy_username=your-username
# proxy_username and proxy_password handle authentication if required
# leave these out if the proxy does not require credentials
If you are debugging local firewall rules, ensure firewall-cmd --list-all shows the expected ports open. DNF uses standard HTTP and HTTPS ports. firewall-cmd --reload after every rule change. Otherwise the runtime config and the persistent config diverge.
Check the repo file syntax. A missing bracket or typo in /etc/yum.repos.d/ stops DNF cold.
Verify it worked
Once you have applied the fix, verify that DNF can synchronize the cache and list available updates. The check-update command queries all enabled repositories and reports available upgrades without installing anything. This confirms the cache is healthy and the repositories are accessible.
Here's how to verify the synchronization succeeded.
sudo dnf check-update
# check-update queries repos and lists available upgrades without installing anything
# a list of packages with versions indicates success
# "No matches found" also indicates success if the system is fully updated
If you see a list of packages, the cache is synchronized. You can proceed with sudo dnf upgrade. If you see an error, review the error message carefully. It will point to the specific repository or configuration issue that remains.
Run dnf check-update to verify. A list of packages means the cache is synchronized and ready.
Common pitfalls
SELinux denials can block DNF network access, though this is rare. DNF runs in the dnf_t domain and requires network permissions to fetch metadata. If the policy is restrictive, DNF might be denied name_connect on the network socket. This results in a connection error that looks like a network failure. SELinux denials show up in journalctl -t setroubleshoot with a one-line summary. Read those before disabling SELinux.
Here's how to check for SELinux denials related to DNF.
journalctl -t setroubleshoot | tail -20
# -t filters by syslog identifier to isolate SELinux messages
# setroubleshoot translates raw AVC denials into human-readable suggestions
# look for messages mentioning dnf or yum and network access
If you see denials, restore the correct context on the repository files or reload the policy. Running restorecon -Rv /etc/yum.repos.d/ often fixes context issues. Disabling SELinux is not the solution. It exposes the system to other risks.
Another pitfall is editing the wrong file. DNF reads configuration from /etc/dnf/dnf.conf for global settings and /etc/yum.repos.d/*.repo for repository definitions. Changes to dnf.conf affect all repositories. Changes to repo files affect only the specific repository. Ensure you are editing the correct file for the repository that is failing.
You may also encounter GPG key errors that look like synchronization failures. If DNF downloads the metadata but the GPG check fails, the error message will mention GPG check FAILED. This is a different issue. The metadata is synchronized, but the signature verification failed. Import the missing key or update the GPG keys to resolve this.
Trust the package manager. Manual file edits drift, snapshots stay.
When to use this vs alternatives
Use dnf clean all when the cache is suspected to be corrupted or after a manual edit to repo files. Use dnf makecache when you want to pre-download metadata for offline work or to verify repository health. Use baseurl in repo files when the mirrorlist is broken or you are in an isolated environment with a local mirror. Use mirrorlist when you want automatic load balancing and geographic optimization for repository traffic. Use dnf upgrade --refresh for weekly maintenance to ensure metadata is current before applying updates. Use journalctl -xe when DNF fails silently or returns a generic error to find the underlying network or permission issue.