Common Compatibility Issues

# Confirm the current sudo implementation
sudo --version
 
# If a script relies on a traditional sudo feature and fails, temporarily revert
sudo apt install sudo
# This takes over /usr/bin/sudo; switch back to sudo-rs once you've finished debugging

sudo apt install gnu-coreutils

# Export the key to a dedicated keyring
curl -fsSL https://repo.example.com/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
 
# Reference it via Signed-By in the .sources file
# Signed-By: /etc/apt/keyrings/example.gpg

# Old: sudo update-initramfs -u
# New:
sudo dracut -f

# View disabled PPAs
ls /etc/apt/sources.list.d/*.distUpgrade
 
# Error example
# E: The repository 'https://ppa.launchpadcontent.net/example/ppa/ubuntu resolute Release' does not have a Release file.
 
# Check if the PPA supports 26.04
sudo add-apt-repository --list
 
# Remove incompatible PPAs
sudo add-apt-repository --remove ppa:example/ppa
 
# Or manually delete
sudo rm /etc/apt/sources.list.d/example-ppa.sources
sudo apt update

# Many third-party sources use version codenames (e.g., noble, resolute)
# These need to be updated after upgrading
 
# Check the current codename
lsb_release -cs
# Output: resolute
 
# Manually update the version codename in third-party source files
sudo sed -i 's/noble/resolute/g' /etc/apt/sources.list.d/example.list
 
# For DEB822 format
sudo sed -i 's/noble/resolute/g' /etc/apt/sources.list.d/example.sources
 
# Update index
sudo apt update

# Error example
# W: GPG error: https://repo.example.com ... EXPKEYSIG
 
# Re-fetch the key
curl -fsSL https://repo.example.com/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
 
# Remove the expired old key
sudo rm /etc/apt/trusted.gpg.d/example.gpg

# The NVIDIA driver may need to be reinstalled after upgrading
# Check driver status
nvidia-smi
 
# If the command is unavailable, reinstall the driver
sudo ubuntu-drivers devices
sudo ubuntu-drivers autoinstall
 
# Let ubuntu-drivers pick the matching driver version automatically
# The exact version number should follow the "recommended" line from ubuntu-drivers devices
sudo ubuntu-drivers autoinstall
 
# If stuck at low resolution or black screen
# 1. Switch to TTY: Ctrl+Alt+F2
# 2. Reinstall the driver (version per ubuntu-drivers devices)
sudo apt install --reinstall nvidia-driver-XXX
sudo reboot

# Check DKMS status
dkms status
 
# If modules are not built
sudo dkms autoinstall
 
# Manually rebuild a specific module
sudo dkms build module-name/version -k $(uname -r)
sudo dkms install module-name/version -k $(uname -r)
 
# Common modules that require DKMS
# - VirtualBox Guest Additions
# - NVIDIA driver
# - ZFS
# - WireGuard (older kernels)

# Check wireless devices
rfkill list all
iwconfig
 
# Install missing firmware
sudo apt install linux-firmware -y
 
# If a specific network card doesn't work
lspci | grep -i network
lsusb | grep -i wireless
 
# Check kernel logs for firmware errors
dmesg | grep -i firmware
dmesg | grep -i wifi
 
# Reload the wireless module
sudo modprobe -r iwlwifi && sudo modprobe iwlwifi

# Check PipeWire (default in 26.04) or PulseAudio
systemctl --user status pipewire pipewire-pulse
 
# Restart audio services
systemctl --user restart pipewire pipewire-pulse
 
# If migrating from PulseAudio to PipeWire
sudo apt install pipewire-audio

# Check Python version
python3 --version
 
# The Python minor version may change after upgrading (e.g., 3.12 -> 3.13)
# Note: the 26.04 system Python is protected by PEP 668 and cannot install packages
# directly with pip (including --user). Reinstall dependencies inside a virtual environment —
# after a minor version change the old venv usually needs to be rebuilt:
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
 
# For global command-line application tools, install/reinstall with pipx instead:
# sudo apt install pipx
# pipx reinstall-all

# Check PHP version
php -v
 
# The PHP version may change from 8.3 to 8.5 after upgrading
# Web server configurations need to be updated
 
# Nginx - update PHP-FPM socket path
# Old: fastcgi_pass unix:/run/php/php8.3-fpm.sock;
# New: fastcgi_pass unix:/run/php/php8.5-fpm.sock;
sudo grep -r "php8." /etc/nginx/
 
# Apache - update modules
sudo a2dismod php8.3
sudo a2enmod php8.5
sudo systemctl restart apache2
 
# Reinstall PHP extensions
sudo apt install php8.5-mysql php8.5-curl php8.5-mbstring php8.5-xml -y

# Check version
mysql --version
 
# Note: MySQL 8.4 removed the mysql_upgrade command;
# the data dictionary upgrade is now performed automatically when mysqld starts,
# so no manual step is needed. Only MariaDB still requires a manual upgrade:
sudo mariadb-upgrade -u root -p
 
# Check table compatibility
sudo mysqlcheck -u root -p --all-databases --check-upgrade
 
# If errors occur, try repair
sudo mysqlcheck -u root -p --all-databases --auto-repair

# PostgreSQL may need data directory migration after upgrade
# Check version
pg_lsclusters
 
# If there are multiple cluster versions (e.g., upgrading from 16 on 24.04 to 18 on 26.04)
# The old cluster is preserved after upgrade
sudo pg_upgradecluster 16 main 18
 
# After confirming the new cluster works, drop the old one
sudo pg_dropcluster 16 main

# If installed via system packages
node --version
 
# It is recommended to use nvm for version management, unaffected by system upgrades
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

# Configuration files where you chose "install the package maintainer's version"
# during the upgrade -- old versions are backed up as .dpkg-old
find /etc -name "*.dpkg-old" 2>/dev/null
find /etc -name "*.dpkg-dist" 2>/dev/null
find /etc -name "*.ucf-dist" 2>/dev/null
 
# Compare differences
diff /etc/ssh/sshd_config /etc/ssh/sshd_config.dpkg-old

# Use diff3 for a three-way merge
# Requires the original config, your modifications, and the new version config
 
# For debconf-managed configs
sudo dpkg-reconfigure package-name
 
# Reconfigure all ucf-managed configuration files
sudo ucf --purge /etc/some/config
sudo apt install --reinstall package-name

# Check if there are services that need reloading
sudo systemctl daemon-reload
 
# View overridden service files
systemd-delta
 
# Check if custom overrides are still effective
systemctl cat your-service.service

# Some service names may change in the new version
# For example:
# iptables -> nftables
# isc-dhcp-server -> kea-dhcp4-server
 
# Check if a service exists
systemctl list-unit-files | grep service-name

# Reinstall GRUB
sudo grub-install /dev/sda   # or your boot disk
sudo update-grub
 
# View GRUB configuration
cat /boot/grub/grub.cfg | grep menuentry

# If autoremove cannot remove old kernels
dpkg --list | grep linux-image
 
# Manually remove a specific old kernel
sudo apt purge linux-image-5.15.0-xx-generic
sudo apt purge linux-headers-5.15.0-xx-generic
sudo update-grub

# GNOME Shell version may change after upgrading
gnome-shell --version
 
# Disable all extensions
gsettings set org.gnome.shell disable-user-extensions true
 
# Enable one at a time and test
gnome-extensions list
gnome-extensions enable extension-name@example.com
 
# Update extensions
# Visit https://extensions.gnome.org to reinstall

# Check current display protocol
echo $XDG_SESSION_TYPE
 
# Some apps don't support Wayland; force X11 backend
GDK_BACKEND=x11 application-name

# Check Docker service status
sudo systemctl status docker
 
# If the Docker repository codename hasn't been updated
# Reconfigure the Docker source
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
sudo apt update
sudo apt install --only-upgrade docker-ce docker-ce-cli -y
 
# Verify
docker run hello-world
docker compose version

# 1. View system logs
sudo journalctl -b -p err
sudo journalctl -b -p warning | head -50
 
# 2. View specific service logs
sudo journalctl -u service-name --since "1 hour ago"
 
# 3. Check package integrity
sudo debsums -c  # check modified configuration files
sudo debsums -s  # silent mode, show errors only
 
# 4. Reconfigure a package
sudo dpkg-reconfigure package-name
 
# 5. View upgrade logs
less /var/log/dist-upgrade/main.log
less /var/log/dist-upgrade/apt.log