This page provides solutions and diagnostic steps for common issues encountered when using NX AppHub CLI.

Whether you're encountering build failures, missing dependencies in your custom bundle, or issues with PPA integration, this guide will help you identify and resolve the most common errors.

For best results, please ensure you're using the latest version of the tool and that your YAML configuration follows the correct schema.

• Cause:

  • The package is either misspelled, unavailable in the listed distrorepo, or in a component (like universe) the user didn't specify.

• Fix:

  • Double-check the spelling of the package name in deps.
  • If using Ubuntu, add missing components:

components: [main, universe]

Use tools like apt search or apt-file in a Distrobox container (see our tutorial on how to use Distrobox) or explore package mirrors manually.

• Debian Packages
• Ubuntu Packages Search
• Devuan Package Information

• Cause:

  • The curated YAML declares buildinfo.os-target and it does not match the host Nitrux VERSION_ID.

• Fix:

  • Update Nitrux to the target release used by that app entry, or
  • Use a YAML that targets your current Nitrux version.

To inspect your host version:

grep '^VERSION_ID=' /etc/os-release

• Cause:

  • The PPA string is incorrectly formatted.

• Fix:

  • Use ppa: user/ppa-name, not a URL or shorthand.

• Cause:

  • A dependency references a PPA id that's not defined.

• Fix:

  • Define the PPA in distrorepo.ppas with a matching id.

NX AppHub CLI includes a linter that scans an extracted AppDir directory (like squashfs-root/) and:

• Detects missing shared libraries (i.e., those that would break the app at runtime).

It will:

• Normalize the path to detect squashfs-root
• Walk through all ELF binaries and .so files
• Find any libraries reported by ldd as => not found

• Symptom:

error while loading shared libraries: libXYZ.so: cannot open shared object file: No such file or directory

• Cause:

  • Missing runtime shared libraries inside the AppDir.

• Solution:

  • Run nx-apphub-cli using the --appdir-lint option in the build command to find the missing shared libraries.
    • Use tools like apt search in a Distrobox container (see our tutorial on how to use Distrobox) or explore package mirrors manually to find the package providing the missing library.
      • Debian Packages
      • Ubuntu Packages Search
      • Devuan Package Information

nx-apphub-cli build app.yml --appdir-lint squashfs-root/

• Symptom:

/tmp/.mount_myapp-xxxx/usr/bin/myapp: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by /tmp/.mount_myapp-xxxx/usr/bin/myapp)

• Cause:

  • This error occurs when the user runs a bundled application in a Linux distribution with an older version of the GNU C Library (glibc) than the version required by the executable and dynamic libraries inside the AppDir. This error can occur when:
    • The user builds an AppDir using newer .deb packages (e.g., from Debian unstable, Ubuntu noble, etc.), then attempts to run the application in the bundle on an older distribution (e.g., Debian stable, Ubuntu jammy) where the required glibc version (e.g., GLIBC_2.38) is unavailable.

• Solution:

  • If you're building a custom bundle for use outside Nitrux:
    • Use .deb packages from a distribution that matches the GNU C Library (glibc) version of your target runtime environment.
    • Do not use packages compiled for newer distributions (e.g., Debian sid) if you plan to run the bundle on older distributions (e.g., Debian bookworm).

To check the glibc version on your target system:

ldd --version

To check the required glibc version for a binary:

readelf -sW /path/to/binary | grep GLIBC_

Some desktop environments (DEs) and toolkits rely heavily on environment variables to detect the session type, load the correct style plugin, or pick up theme configuration. When building a bundle with NX AppHub CLI, these executables inside may need environment variables that do not automatically match the host system, especially when a sandbox, such as bwrap.

This use case can lead to issues such as:

• Applications are not picking up the expected theme.
• KDE/Kirigami/Maui applications defaulting to their fallback style
• Incorrect Qt plugin or QML import paths
• Wayland/X11 mismatches
• Icon theme discrepancies despite bundling the icons

This section explains how to set environment variables correctly in your YAML file to ensure a bundle behaves consistently across desktop environments.

Any environment variables added under apprunconf.envvars are exported inside the AppDir runtime, before launching the application:

apprunconf:
  envvars:
    QT_QPA_PLATFORM: "wayland;xcb"
    QT_PLUGIN_PATH: "$APPDIR/usr/lib/x86_64-linux-gnu/qt6/plugins"
    QT_QPA_PLATFORMTHEME: ""

• Symptom:

  • Some applications will work correctly only when unsetting some of the host environment variables or overriding them, for example:

QT_QPA_PLATFORMTHEME=kde

• Cause:

  • If the AppDir does not contain a matching platform theme plugin, the application may fail to style properly.

• Solution:

  • To prevent this, unset such variables in the sandbox:

sandbox:
  type: bwrap
  bwrap-unset-env:
    - DISPLAY
    - QT_QPA_PLATFORMTHEME

Ensuring the sandboxed AppRun only sees values defined inside apprunconf.

• Symptom:

  • Some toolkits, such as Qt6, KDE Frameworks 6, Kirigami, and MauiKit, rely on certain environment variables to detect whether they are running in a "KDE-compatible environment." For example, KDE Plasma automatically sets these variables:

XDG_CURRENT_DESKTOP=KDE
KDE_FULL_SESSION=true
KDE_SESSION_VERSION=6
XDG_CONFIG_DIRS=/home/user/.config/kdedefaults:/etc/xdg

• Cause:

  • In other sessions (e.g., Hyprland, GNOME, Sway, i3, etc.), these variables do not exist, causing Qt/KF/Maui apps to fall back to a generic style, even if icons and plugins are present in the AppDir.

• Solution:

  • Provide KDE session hints inside the AppRun:

apprunconf:
  envvars:
    XDG_CURRENT_DESKTOP: "KDE"
    KDE_FULL_SESSION: "true"
    KDE_SESSION_VERSION: "6"
    XDG_CONFIG_DIRS: "$HOME/.config/kdedefaults:/etc/xdg"
    QT_QPA_PLATFORMTHEME: ""

This solution allows Qt/KF/Maui applications to load the correct theme engine even when running on non-KDE environments.

• Symptom:

Some applications fail to load the correct Qt style plugin (Breeze, Maui, Kirigami).

• Cause:

  • Plugin paths and import paths are set in the runtime environment.

• Solution:

  • Add the necessary environment variables to the AppRun.

apprunconf:
  envvars:
    QT_PLUGIN_PATH: "$APPDIR/usr/lib/x86_64-linux-gnu/qt6/plugins"
    QT_QML_IMPORT_PATH: "$APPDIR/usr/lib/x86_64-linux-gnu/qt6/qml"
    QML_IMPORT_PATH: "$APPDIR/usr/lib/x86_64-linux-gnu/qt6/qml"
    QML2_IMPORT_PATH: "$APPDIR/usr/lib/x86_64-linux-gnu/qt5/qml"

• Symptom:

  • Bundle fails to build due to the wrong YAML syntax.

• Solution:

  • Ensure your YAML has the correct structure. For example:

  distrorepo:
    base:
      - distro: ubuntu
        release: oracular
        arch: amd64
        components: [main, universe]
    ppas:
      - id: inkscape-dev
        ppa: inkscape.dev/stable
        distro: ubuntu
        release: oracular
        arch: amd64

  distrorepo:
    - distro: debian
      release: testing
      arch: amd64

To include a YAML file in the curated central Git-based repository NX AppHub Apps, the resulting bundle must work in Nitrux and comply with the canonical AppBox policy (curated YAML source, Nitrux baseline alignment, trusted repository policy, and curated runtime/sandbox rules); see FAQ → 1. Why are the files called AppBoxes?.

Testing that a YAML produces a functional bundle for Nitrux is easily achieved in a few steps.

1. Create a work directory, i.e., ~/Build/nx-apphub and switch to it.

mkdir -p ~/Build/nx-apphub && ~/Build/nx-apphub

2. Generate a YAML file, see 1.3 Generating a template YAML and build it, see 1.4 Building and validating a YAML file.

3. Once NX AppHub CLI builds a bundle, simply run it.

   • For finding missing libraries, see 3.1 Problem: bundle launches with missing .so errors.

4. Repeat steps 2 and 3 until the bundle launches in Nitrux.

While we don't guarantee that the YAML definitions fetched by NX AppHub CLI from NX AppHub Apps will work in other Linux distributions, as noted in 4. Do AppBoxes work on other Linux distributions?. We recognize that some users reasonably expect their custom bundles to work across Linux distributions.

Since NX AppHub CLI allows users to define their own YAML files, users are free to test and adapt their builds for broader portability, but doing so is optional and outside the core goals of this project.

Regardless, below is our recommended process for testing their portability.

First, create a container of another distribution using Distrobox (see our tutorial on how to use Distrobox), then run the custom bundle in that container.

For example, use Arch Linux and Fedora to test the bundle:

1. Create both containers.

distrobox create -n arch-dbox -i quay.io/toolbx/arch-toolbox:latest
distrobox create -n fedora-dbox -i registry.fedoraproject.org/fedora-toolbox:latest

2. Create a work directory, i.e., ~/Build/nx-apphub and switch to it.

mkdir -p ~/Build/nx-apphub && cd ~/Build/nx-apphub

3. On separate tabs, enter each container.

[Tab #1] distrobox enter arch-dbox
[Tab #2] distrobox enter fedora-dbox

4. Install the required dependencies to run bundles.

For Arch Linux: 
    - sudo pacman -S fuse2 fuse3

For Fedora:
    - sudo dnf install fuse fuse3 fuse-libs

5. Generate a YAML file, see 1.3 Generating a template YAML to build an AppBox and build it, see 1.4 Building and validating a YAML file.

6. Once NX AppHub CLI builds a custom bundle, simply run the file within the container.

   • For finding missing libraries, see 3.1 Problem: AppBox launches with missing .so errors.

7. Repeat steps 4 and 5 until the custom bundle launches in the container(s).