Android Package Name Validation Logic in UAD-NG: Requirements and Error Handling

UAD-NG validates package IDs by checking for non-empty strings and relies on Android's ADB subsystem to enforce package naming rules, converting low-level errors into user-friendly messages.

The Universal Android Debloater Next Generation (UAD-NG) treats a package ID as the Android package name used in ADB pm commands. Rather than implementing complex regular-expression validators, the codebase uses lightweight runtime checks that defer to Android's own grammar enforcement. This approach minimizes validation overhead while ensuring users receive clear feedback when package names violate system requirements.

How UAD-NG Validates Package IDs

The validation strategy in UAD-NG focuses on two critical checkpoints: preventing empty strings from reaching ADB and intercepting Android's native error responses.

Empty String Detection in sync.rs

The primary validation occurs in crates/uad-core/src/sync.rs, where the make_friendly_error_message function intercepts ADB errors before they reach the user interface. When the underlying ADB shell command receives an empty package name, Android returns the error "Shell cannot change component state for null". The Rust code captures this specific string pattern and transforms it into actionable guidance:

// In crates/uad-core/src/sync.rs
if error_output.contains("Shell cannot change component state for null") {
    return format!(
        "Invalid package: Empty package name detected.\n\
         Error: {error_output}\n\
         Tip: Please refresh the package list and try again."
    );
}

This error-handling logic acts as the de facto validation layer for malformed input, ensuring users understand that the operation failed due to an empty package identifier.

ADB Error Handling and Validation

The run_adb_shell_action function in the same file forwards any ADB errors containing the null component message back to the GUI as an "Invalid package" error. This mechanism effectively blocks operations on invalid names without requiring UAD-NG to maintain its own regex engine for Android's complex naming rules.

Android Package Name Requirements

While UAD-NG does not rigidly enforce Android's package-name grammar internally, the application operates within the constraints of the Android Package Manager's validation rules. According to the ADB subsystem used by UAD-NG, valid package names must follow these specifications:

• A series of identifiers separated by periods (.)
• Each identifier must start with a lower-case letter (a-z)
• Subsequent characters may be lower-case letters, digits, or underscores (_)
• The complete name must contain ≤ 255 characters
• The name cannot be empty

When users manually enter package names that deviate from these rules—such as including uppercase letters or special characters—the ADB command itself fails. UAD-NG then surfaces this failure through the error-handling logic in sync.rs, providing the same user-friendly "Invalid package" message without distinguishing between empty names and grammatically invalid ones.

UI-Level Validation and Package Lists

Beyond the core ADB error handling, UAD-NG implements preventive measures in the user interface to reduce validation failures.

PackageRow Widget Constraints

In crates/uad-gui/src/widgets/package_row.rs, the action button only appears for packages with non-empty identifiers. The UI constructs action buttons using the CorePackage entries loaded from the official list, ensuring that null or empty strings never trigger ADB commands:

// In crates/uad-gui/src/widgets/package_row.rs
let action_btn = button(
    text(action_text)
        .align_x(alignment::Horizontal::Center)
        .width(100),
)
.on_press(Message::ActionPressed);

Trusted Package List Validation

The application ships with resources/assets/uad_lists.json, which contains the master list of debloatable packages. Every entry in this JSON file follows Android's package-name conventions, meaning the GUI never presents invalid identifiers from this curated source. When users manually add packages through the "Add package" modal, the code checks that the string is non-empty before adding it to the operation queue, leaving Android's ADB layer to enforce the remaining grammatical rules.

Summary

• UAD-NG performs minimal explicit validation, checking only that package IDs are non-empty strings before sending them to ADB.
• Error handling in crates/uad-core/src/sync.rs converts Android's "Shell cannot change component state for null" errors into user-friendly "Invalid package" messages.
• Android's ADB subsystem enforces the actual grammar rules, rejecting names that don't start with lowercase letters, contain invalid characters, or exceed 255 characters.
• The UI prevents empty package operations by only displaying action buttons for valid CorePackage entries sourced from the curated JSON list.
• Manual entries are filtered at the UI level for empty strings, with ADB providing the final validation for Android-specific naming requirements.

Frequently Asked Questions

What validation does UAD-NG perform on package IDs?

UAD-NG checks that package IDs are non-empty strings before submitting them to ADB. The code in crates/uad-core/src/sync.rs specifically looks for the error "Shell cannot change component state for null" to detect empty package names. Beyond this empty-string check, UAD-NG does not implement regular-expression validation for Android's package naming rules, instead relying on the ADB subsystem to reject grammatically invalid names.

How does UAD-NG handle invalid Android package names?

When ADB encounters an invalid package name—whether empty or grammatically malformed—it returns a shell error. The make_friendly_error_message function in crates/uad-core/src/sync.rs intercepts these errors and returns a formatted message stating "Invalid package: Empty package name detected" along with the raw error output and a suggestion to refresh the package list. This error bubbles up to the GUI, where the operation is blocked and the user receives clear feedback.

Where does UAD-NG define package name validation rules?

Validation logic is distributed across two main locations. The ADB error handling resides in crates/uad-core/src/sync.rs, where the run_adb_shell_action and make_friendly_error_message functions process shell output. UI-level preventive measures exist in crates/uad-gui/src/widgets/package_row.rs, which ensures action buttons only appear for packages with valid identifiers from the curated list. The project does not contain a dedicated validation module with regex patterns, as it defers to Android's built-in package name enforcement.

What are Android's official package name requirements?

Android package names must consist of dot-separated identifiers where each segment starts with a lowercase letter (a-z) and may continue with lowercase letters, digits, or underscores (_). The entire string must not exceed 255 characters and cannot be empty. UAD-NG respects these rules indirectly by passing all package names to ADB, which enforces these constraints at the system level and returns errors for any violations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}