Skip to main content

​
Installation Issues

​
Terra repository not found

Problem: DNF cannot access the Terra repository.Solutions:
  1. Check your network connection: 
    ping repos.fyralabs.com
  2. Verify the repository URL is correct: 
    cat /etc/yum.repos.d/terra.repo
  3. Check if your Fedora version is supported: 
    cat /etc/fedora-release
    Terra supports current Fedora releases. Very old releases may not be supported.
  4. Reinstall terra-release: 
    sudo dnf remove terra-release
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
Problem: Package manager cannot verify GPG signatures.Solutions:
  1. Import GPG keys manually: 
    sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-terra
  2. Check if terra-release is properly installed: 
    rpm -q terra-release
  3. Reinstall terra-release to get fresh keys: 
    sudo dnf reinstall terra-release
The initial installation of terra-release requires --nogpgcheck because the GPG keys haven’t been installed yet. After installation, all packages are verified.

​
Immutable/Atomic Fedora issues

Problem: Standard DNF commands don’t work on immutable editions.Solution:Use rpm-ostree instead of dnf:
# First, add the repository configuration
curl -fsSL https://github.com/terrapkg/subatomic-repos/raw/main/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo

# Then install terra-release
sudo rpm-ostree install terra-release

# Reboot to apply changes
sudo systemctl reboot
Problem: Packages installed with rpm-ostree require a reboot.Solution:Reboot your system to apply the changes:
sudo systemctl reboot
Alternatively, you can check pending deployments:
rpm-ostree status

​
Package Management Issues

​
Package conflicts

Problem: A package from Terra conflicts with one from another repository.Solutions:
  1. Check which repositories provide the package: 
    dnf repoquery --whatprovides <package-name>
  2. Specify the repository explicitly: 
    sudo dnf install --repo=terra <package-name>
  3. Remove conflicting package first: 
    sudo dnf remove <conflicting-package>
sudo dnf install <package-name>
  4. For subrepo packages, verify you need that subrepo:
    Terra subrepos (extras, mesa, nvidia) may intentionally conflict with packages from other repositories. Only install subrepos if you understand the conflicts.
Problem: DNF cannot resolve package dependencies.Solutions:
  1. Update your system first: 
    sudo dnf upgrade --refresh
  2. Check if you have all required repositories: 
    dnf repolist
    For EL10, ensure EPEL is installed: 
    sudo dnf install 'https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm'
  3. Try the —best flag to see more details: 
    sudo dnf install --best <package-name>
  4. Check package availability: 
    dnf search --repo=terra <package-name>

​
Package not found

Problem: A package you’re looking for doesn’t exist in Terra.Solutions:
  1. Search with a broader term: 
    dnf search <broader-term>
  2. Check online package databases:
  3. For EL users, verify package availability:
    Not all packages in Terra are available in Terra EL. Some packages may only be available in the Fedora version.
  4. Request the package: If the package doesn’t exist in Terra, you can request it to be added.
Problem: Package is found but installation fails.Solutions:
  1. Check repository status: 
    dnf repolist all | grep terra
    Ensure Terra repos are enabled.
  2. Clear DNF cache: 
    sudo dnf clean all
sudo dnf makecache
  3. Check system architecture: 
    uname -m
    Ensure the package is built for your architecture (x86_64, aarch64, etc.).
  4. Check the full error message: Run with verbose output: 
    sudo dnf install -v <package-name>

​
Update Issues

Problem: Package updates fail during installation.Solutions:
  1. Check available disk space: 
    df -h /
    Ensure you have sufficient space for updates.
  2. Clean up old packages: 
    sudo dnf autoremove
sudo dnf clean packages
  3. Try updating one package at a time: 
    sudo dnf update <package-name>
  4. Check for locked databases: 
    sudo rm -f /var/lib/rpm/.rpm.lock
sudo rpm --rebuilddb
Problem: Application stops working after a Terra update.Solutions:
  1. Check application logs: 
    journalctl -u <service-name>
    or for desktop applications: 
    <application-name> --verbose
  2. Verify dependencies are updated: 
    sudo dnf upgrade
  3. Downgrade to previous version temporarily: 
    sudo dnf downgrade <package-name>
  4. Report the issue: File a bug report on the Terra GitHub repository with:
    • Package name and version
    • Error messages or logs
    • Steps to reproduce
    • System information (cat /etc/os-release)

​
Subrepo Issues

Problem: Problems after installing terra-release-nvidia.Solutions:
  1. Verify secure boot status: 
    mokutil --sb-state
    NVIDIA drivers may require secure boot to be disabled or properly configured.
  2. Check driver is loaded: 
    lsmod | grep nvidia
  3. Rebuild kernel modules: 
    sudo akmods --force
sudo dracut --force
  4. Check for conflicts with nouveau: 
    lsmod | grep nouveau
    Nouveau should be blacklisted when using proprietary drivers.
See the NVIDIA-specific documentation in /home/daytona/workspace/source/anda/system/nvidia/README.md for more details.
Problem: Issues after installing terra-release-mesa.Solution:
The Mesa subrepo contains a patched and codec-complete Mesa that conflicts with the standard Fedora Mesa packages.
  1. Ensure you need the patched Mesa: The Terra Mesa is designed for specific codec support. If you don’t need these features, use standard Mesa.
  2. Remove and reinstall if needed: 
    sudo dnf remove terra-release-mesa
sudo dnf distro-sync
  3. Check which Mesa is installed: 
    dnf repoquery --installed mesa\*

​
Enterprise Linux (EL) Specific Issues

Problem: Terra EL requires EPEL but it’s not installed.Solution:Install EPEL for EL10:
sudo dnf install 'https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm'
Verify installation:
dnf repolist | grep epel
Problem: A package available on Fedora Terra is not available on Terra EL.Solution:
Not all packages in Terra are available for EL. This is expected due to differences between Fedora and Enterprise Linux.
  1. Check if the package is available: 
    dnf search --repo=terra <package-name>
  2. Request EL support for the package: File an issue on the Terra GitHub repository requesting EL support.
  3. Consider alternative packages: Search EPEL and other EL-compatible repositories.

​
Performance Issues

Problem: Package manager operations take too long.Solutions:
  1. Enable fastest mirror: 
    echo 'fastestmirror=True' | sudo tee -a /etc/dnf/dnf.conf
  2. Increase parallel downloads: 
    echo 'max_parallel_downloads=10' | sudo tee -a /etc/dnf/dnf.conf
  3. Clean metadata cache: 
    sudo dnf clean metadata
sudo dnf makecache
  4. Check repository mirrors: Some repository mirrors may be slow. The metadata will automatically use faster mirrors.

​
Getting More Help

If your issue isn’t covered here:

Join the Community

Get real-time help from Terra users and maintainers in community chat channels.

Report a Bug

File a detailed bug report on GitHub for investigation by maintainers.

Check FAQ

Review frequently asked questions for additional information.

Security Issues

Report security vulnerabilities through GitHub’s security advisory system.

​
Contributing Fixes

Found a solution to a problem not listed here? Consider contributing to this documentation:
  1. The documentation source is available in the Terra repository
  2. Submit improvements via pull request
  3. Help other users by sharing your solutions
Your contributions make Terra better for everyone!

Build docs developers (and LLMs) love

Get started for freeTalk to us