Fixing 'cannot refresh cache whilst offline' in Linux and cPanel

When running administration consoles (such as Cockpit or PackageKit/pkcon) or package management tools (such as dnf and yum) in a Linux terminal, you may encounter the message: Cannot refresh cache whilst offline.

While it looks like a generic internet disconnection warning, the failure typically stems from a mismatch between expired local repository metadata and failed network connection attempts to upstream mirrors.

Here is the technical breakdown under the hood, the system calls involved, the diagnostic steps, and methods to resolve or bypass the issue.

1. What happens under the hood?#

The error occurs when the package manager needs to refresh expired metadata but cannot complete TCP handshakes with repository mirrors.

The underlying system call sequence illustrates this flow:

1. socket(AF_INET, SOCK_STREAM, 0): The process creates a TCP socket to query repository mirrors.
2. connect(): The kernel initiates the connection. If the default gateway is missing or DNS fails, the kernel returns EHOSTUNREACH ("No route to host") or ETIMEDOUT.
3. openat() and fstat(): Concurrently, DNF inspects metadata files in /var/cache/dnf/. If metadata_expire has elapsed, it must refresh from the network. Receiving transport errors, the tool aborts with the offline warning.

2. Terminal diagnostic workflow#

To isolate whether the issue is caused by network routing, DNS, or corrupt cache databases:

A. Validate default routes and DNS resolution#

# Check default gateway
ip route show

# Validate DNS lookups
cat /etc/resolv.conf
getent hosts google.com

B. Tracing syscalls with strace#

To identify where the failure occurs:

strace -e trace=network,open,stat dnf makecache

Immediate returns of ECONNREFUSED or EHOSTUNREACH right after connect() indicate firewall rules or routing table misconfigurations.

C. Inspecting active network sockets#

lsof -i -P -n | grep dnf

3. Practical remediation methods#

Depending on operational requirements, apply one of three approaches:

Method 1: Force cache-only mode (offline operation)#

When external networking is temporarily unavailable and you need to query or install local packages:

# On DNF:
dnf -C list installed

# On YUM:
yum -C check-update

The -C flag (or --cacheonly in DNF/YUM) forces the package manager to read directly from local caches (/var/lib/dnf/), bypassing mirror connection attempts.

Method 2: Clean and rebuild repository metadata#

If network connectivity is restored but SQLite cache files are corrupt:

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

Method 3: Adjust timeout and metadata expiration#

To prevent transient network hiccups from triggering offline panics, configure resilient thresholds in /etc/dnf/dnf.conf:

[main]
timeout=30
retries=3
metadata_expire=86400  # Keeps metadata valid for 24 hours

4. Frequent edge cases#

1. Stale proxy environment variables: If an unreachable proxy is exported in http_proxy or https_proxy, DNF fails to connect. Check with env | grep -i proxy.
2. Immutable attributes (chattr +i): If /var/cache/dnf has immutable flags applied during security hardening, writes fail. Inspect with lsattr -d /var/cache/dnf.
3. Inode exhaustion: If the /var filesystem runs out of available inodes (100% inode utilization), temporary metadata files cannot be created. Check with df -i.

5. Maximum verbosity debugging#

To identify the exact mirror endpoint returning errors:

dnf -d 10 makecache

Debug level 10 outputs full HTTP request headers, mirror URLs, and Python tracebacks.

Practical lessons on package cache management#

1. Use -C (--cacheonly) for local queries: When network connectivity fluctuates, the cache-only flag allows administrative tasks to proceed smoothly.
2. Understand metadata_expire lifecycles: Extending cache expiration reduces unnecessary network requests during automated deployments.
3. Check the network stack before clearing cache: Often, the root cause is simply an unresolvable DNS server in /etc/resolv.conf.

See also

Linux Extracting 7z archives in Linux via CLI: from basics to low-level troubleshooting

Servers From 'no route to host' to virtual host: debugging standalone Nginx and cloud networking

Servers Low-level debugging in CloudLinux: syscalls, LVE limits, and the trap of unlimited defaults

This post is licensed under CC BY-NC.