Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

dnf "Error: Failed to download metadata for repo": read the reason after the colon

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

The error "Failed to download metadata for repo" followed by the repository name in quotes, a colon and a reason (in the form 'repo-id': reason text) means DNF could not fetch, or could not accept, the package list files for that one repository. The sentence after the colon is the cause, so read it before touching anything. Causes include a repository that no longer exists, a mirror list that returns no addresses, a proxy or firewall in the way, a certificate that fails, and a slow link that times out.

On CentOS Linux 8 the first cause applies. The CentOS Project's notice says CentOS Linux 8 "will reach End Of Life (EOL) on December 31st, 2021", and that its content "will be removed from our mirrors, and moved to vault.centos.org where it will be archived permanently". No setting makes an ended release current again.

What the error means

In DNF 4, the text is built in libdnf: the format is "Failed to download metadata for repo '%s': %s". The first %s is the repository ID (the name in square brackets in its .repo file). The second is the message from librepo, the library that does the download. The DNF 5 source raises its own error text ("Failed to download metadata"), and DNF 5 is not covered here.

Some librepo messages arrive with a prefix. When DNF cannot work out where to download from, librepo adds "Cannot prepare internal mirrorlist: " to the message that explains why. One such message in the librepo source is "No URLs in mirrorlist", so the full line you see ends with both parts joined. It means the repository's mirrorlist or metalink address answered, but gave back no usable download addresses.

A repository section needs at least one source of addresses. The DNF configuration reference says the minimal repository configuration "consists of baseurl, metalink or mirrorlist option definition". baseurl is a list of URLs tried in order. mirrorlist and metalink point to a service that returns addresses. For a standard YUM-style repository, librepo's code names the metadata index file repodata/repomd.xml under the repository address.

The settings that decide how a download fails

These DNF options, from the configuration reference, shape what you see:

Option Documented default Effect
timeout 30 seconds Seconds to wait for a connection, used together with minrate
minrate 1000 bytes per second If the server sends at or below this rate for at least timeout seconds, DNF aborts the connection
sslverify True If the certificate cannot be verified, "connecting fails and the repository is not used any further"
skip_if_unavailable False If enabled, DNF continues and disables the repository that could not be synchronised
metadata_expire 48 hours How long cached metadata is trusted before DNF checks again
proxy none A proxy URL; the curl environment variables such as http_proxy apply when it is unset

The configuration reference also says a distribution may set skip_if_unavailable in its own configuration file, so the default on your host may be different.

Likely causes

Cause What you see after the colon How to confirm
Release ended; repository removed A download error for the metadata index, or "No URLs in mirrorlist" Repository address in the .repo file returns an error when fetched; OS release is past its end-of-life date
Mirror list or metalink empty "Cannot prepare internal mirrorlist: No URLs in mirrorlist" Fetch the mirrorlist or metalink address by hand; it returns no addresses
Wrong release variable Address contains the wrong version The URL after DNF substitutes $releasever and $basearch is wrong
Name resolution or firewall A host-name lookup failure or a connection timeout getent ahosts on the host name; curl to the address from the same server
Proxy required or wrong A proxy error, or timeouts on this server only proxy in dnf.conf or the repo file; http_proxy and https_proxy environment variables
Certificate does not verify A certificate verification failure curl -v shows the certificate error; sslverify is True
Slow link aborted A timeout or an aborted, slow transfer Transfer rate below minrate for timeout seconds
Stale or damaged cache Error persists after the cause is fixed dnf clean metadata then dnf makecache succeeds
Credentials needed An HTTP authorisation error Repository requires username and password, or client certificate settings

Prove the cause before changing anything

  1. Reproduce with the command the DNF manual documents for this: dnf makecache "downloads and caches metadata for enabled repositories". Note the repository ID and the reason after the colon.
  2. Read the repository's configuration. DNF reads .repo files from the directories listed in its reposdir setting. Find the section with the ID from the error and read baseurl, metalink or mirrorlist, proxy, sslverify, enabled and any username.
  3. Fetch the address by hand from the same server, so the same network path is tested. The curl manual says -s with -S shows errors only, -I fetches headers and -L follows redirects:
curl -sS -I -L --max-time 30 https://repo.example.com/el8/x86_64/repodata/repomd.xml

Use your repository's real address, with $releasever and $basearch replaced by the values DNF would use. A 404 means the repository path is gone. A certificate error is reported by curl in plain words. A timeout points to the network.

  1. For a mirrorlist or metalink address, fetch it with curl -sS and read the answer. An empty list produces "No URLs in mirrorlist".
  2. Test name resolution through the system resolver, which the getent manual says uses getaddrinfo for ahosts:
getent ahosts repo.example.com

A failure here is a DNS fault, not a DNF fault. See "Temporary failure in name resolution" on a Linux server: test each layer from systemd-resolved down.

  1. Check whether the release is supported. Read your distribution's lifecycle page; for CentOS Linux 8 the CentOS Project states it "will reach End Of Life (EOL) on December 31st, 2021" and that its content "will be removed from our mirrors, and moved to vault.centos.org where it will be archived permanently".

Example (illustrative): On app01, sudo dnf makecache ends with "Error: Failed to download metadata for repo 'appstream': Cannot prepare internal mirrorlist: No URLs in mirrorlist". The repository file has a mirrorlist address and no baseurl. curl -sS on that address returns an empty body. /etc/os-release shows the server runs CentOS Linux 8. The cause is the retired release, not the network. ping to other sites works, and no proxy is set. The administrator schedules a migration instead of editing the file.

Fix

Retired repository (end-of-life release)

The CentOS Vault page says it "is NOT an updated tree for installing CentOS Linux" but a snapshot of older trees, kept "for reference", and that "we do not put security updates into the trees on this server". Pointing a production server at the vault can make dnf run, but it receives no updates. Plan a move to a supported release. Until then treat the server as unpatched and limit its exposure. If you must install a package from the vault in the short term, test the change on a copy of the server first.

Empty mirror list, wrong variable

Fix the .repo entry so its baseurl, metalink or mirrorlist address returns real answers. The configuration reference says $releasever is substituted from the releasever setting, and the command reference documents --releasever=<release> to "configure DNF as if the distribution release was" another one. Use that to test a different release path without editing files.

Network, proxy and name resolution

Fix the network path found in the checks: DNS, firewall rules for HTTPS to the repository, or the proxy. Set proxy in dnf.conf (or in the repository section) in the documented form <scheme>://<ip-or-hostname>[:port]. Setting it to an empty string in a repository section disables an inherited proxy for that repository.

Certificate failures

sslverify is True by default. Fix the cause, for example by adding the missing authority with sslcacert. Setting sslverify to False is documented to allow SSL connections "but certificates are not verified". Treat that as a diagnostic, not a fix.

Risk: setting sslverify to False means DNF accepts packages and metadata from a server whose identity it has not verified, so anyone able to answer in its place can serve content to the host. Use it for one test at most. To back out, set sslverify back to True (the default) and run sudo dnf clean metadata.

Slow link

If the transfer starts and then stops, raise timeout or lower minrate only after you have confirmed the server is simply slow. These make DNF wait longer for a bad link.

Stale cache

Risk: sudo dnf clean metadata removes the repository metadata and forces a full download next time, which costs bandwidth and time on a slow link. It cannot damage installed packages. Then run sudo dnf makecache.

Skipping one repository

dnf --disablerepo=<id> ... disables the repository for a single command, according to the command reference. Setting skip_if_unavailable to True makes DNF carry on when a repository cannot be reached. Risk: updates from that repository, including security updates, are then silently absent. Use it only as a short bridge, and remove it once the repository is fixed.

Confirm the fix

  1. sudo dnf makecache completes with no "Failed to download metadata" line.
  2. dnf repolist lists the repository. The command reference says it lists enabled repositories by default.
  3. Start your next update and read the package list before you accept it, so you can see that the repository now supplies what you expect.

What to watch afterwards

  • Track end-of-life dates for every distribution you run, and plan migration before the repositories vanish.
  • If you use skip_if_unavailable, alert on repositories skipped, so a silent gap in updates is noticed.
  • Keep a record of proxy and firewall rules that repositories depend on.
  • After an OS upgrade or restore, confirm releasever and repository addresses are right for the new release.

Risks and limits

  • These commands have not been run or lab-tested. They come from the DNF documentation, the project source and the manuals in the Sources list.
  • The message wording comes from libdnf (DNF 4) and librepo source on their main branches. Releases shipped by distributions can differ slightly.
  • DNF 5 shows a different message and is not covered.
  • No supported way to keep using a retired release's normal repositories is described here. The vault is an archive.
  • Disabling certificate checks, or skipping a repository, lowers protection and can hide missing updates.
  • Cached data is per host. Clearing the cache on one server does not affect others.

Sources