termux/termux-app · critical · RuntimeException

Unsupported TERMUX_APP_PACKAGE_VARIANT "%s"

Error message

Unsupported TERMUX_APP_PACKAGE_VARIANT "%s"

What it means

Thrown by TermuxBootstrap.setTermuxPackageManagerAndVariant when packageVariantName does not match any PackageVariant enum value. Valid variants are 'apt-android-7' and 'apt-android-5'. variantOf() does a case-sensitive equality check against the enum names; any other string (including null passed safely returns null before this, but an unrecognized non-empty string) triggers the exception.

Source

Thrown at termux-shared/src/main/java/com/termux/shared/termux/TermuxBootstrap.java:30

    private static final String LOG_TAG = "TermuxBootstrap";

    /** The field name used by Termux app to store package variant in
     * {@link TERMUX_APP#BUILD_CONFIG_CLASS_NAME} class. */
    public static final String BUILD_CONFIG_FIELD_TERMUX_PACKAGE_VARIANT = "TERMUX_PACKAGE_VARIANT";


    /** The {@link PackageManager} for the bootstrap in the app APK added in app/build.gradle. */
    public static PackageManager TERMUX_APP_PACKAGE_MANAGER;

    /** The {@link PackageVariant} for the bootstrap in the app APK added in app/build.gradle. */
    public static PackageVariant TERMUX_APP_PACKAGE_VARIANT;

    /** Set {@link #TERMUX_APP_PACKAGE_VARIANT} and {@link #TERMUX_APP_PACKAGE_MANAGER} from {@code packageVariantName} passed. */
    public static void setTermuxPackageManagerAndVariant(@Nullable String packageVariantName) {
        TERMUX_APP_PACKAGE_VARIANT = PackageVariant.variantOf(packageVariantName);
        if (TERMUX_APP_PACKAGE_VARIANT == null) {
            throw new RuntimeException("Unsupported TERMUX_APP_PACKAGE_VARIANT \"" + packageVariantName + "\"");
        }

        Logger.logVerbose(LOG_TAG, "Set TERMUX_APP_PACKAGE_VARIANT to \"" + TERMUX_APP_PACKAGE_VARIANT + "\"");

        // Set packageManagerName to substring before first dash "-" in packageVariantName
        int index = packageVariantName.indexOf('-');
        String packageManagerName = (index == -1) ? null : packageVariantName.substring(0, index);
        TERMUX_APP_PACKAGE_MANAGER = PackageManager.managerOf(packageManagerName);
        if (TERMUX_APP_PACKAGE_MANAGER == null) {
            throw new RuntimeException("Unsupported TERMUX_APP_PACKAGE_MANAGER \"" + packageManagerName + "\" with variant \"" + packageVariantName + "\"");
        }

        Logger.logVerbose(LOG_TAG, "Set TERMUX_APP_PACKAGE_MANAGER to \"" + TERMUX_APP_PACKAGE_MANAGER + "\"");
    }

    /**
     * Set {@link #TERMUX_APP_PACKAGE_VARIANT} and {@link #TERMUX_APP_PACKAGE_MANAGER} with the
     * {@link #BUILD_CONFIG_FIELD_TERMUX_PACKAGE_VARIANT} field value from the

View on GitHub (pinned to 3df69d1da1)

Solutions

  1. Set TERMUX_PACKAGE_VARIANT in build.gradle to one of the supported values: 'apt-android-7' or 'apt-android-5'.
  2. Trim and lower-case the variant string before lookup if whitespace/case is suspected.
  3. Ensure the build config field name matches BUILD_CONFIG_FIELD_TERMUX_PACKAGE_VARIANT exactly.
  4. If you forked and added a variant, also add it to the PackageVariant enum.

Example fix

// before
public static PackageVariant variantOf(String name) {
    if (name == null || name.isEmpty()) return null;
    for (PackageVariant v : PackageVariant.values()) {
        if (v.name.equals(name)) return v;
    }
    return null;
}

// after (case-insensitive + trimmed lookup with explicit error listing valid values)
public static PackageVariant variantOf(String name) {
    if (name == null) return null;
    String key = name.trim();
    if (key.isEmpty()) return null;
    for (PackageVariant v : PackageVariant.values()) {
        if (v.name.equalsIgnoreCase(key)) return v;
    }
    throw new IllegalArgumentException("Unknown package variant '" + name + "'. Valid: apt-android-7, apt-android-5");
}
Defensive patterns

Strategy: validation

Validate before calling

String v = (packageVariantName == null) ? null : packageVariantName.trim();
if (v == null || PackageVariant.variantOf(v) == null) {
    throw new IllegalArgumentException(
        "Unsupported variant: " + v + ". Valid: apt-android-7, apt-android-5");
}

Try / catch

try {
    TermuxBootstrap.setTermuxPackageManagerAndVariant(variant);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unsupported TERMUX_APP_PACKAGE_VARIANT")) {
        // fallback to default variant or fail build
        throw new BuildException(e.getMessage(), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: TERMUX_PACKAGE_VARIANT build config field is set to an unsupported value (e.g. 'apt-android-6', 'tapm-android-7', 'APT-ANDROID-7' with wrong case, or a typo); a plugin reads a stale/wrong build config field from the Termux app; the variant string has trailing whitespace.

Common situations: Custom build sets an unregistered variant in build.gradle; upgrading introduced a new variant name not yet in the enum; sharedUserId plugin reads a field that does not exist, returning garbage.

Related errors

AI-assisted analysis of termux/termux-app@3df69d1da1 (2026-08-13). Data as JSON: /api/errors/ca6327507e3b1132. Report an issue: GitHub.