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

> Discover Android package name validation rules and error handling in UAD-NG. Learn how UAD-NG enforces package ID requirements using ADB for clear user feedback.

- Repository: [Universal-Debloater-Alliance/universal-android-debloater-next-generation](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation)
- Tags: internals
- Published: 2026-06-20

---

**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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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:

```rust
// 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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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:

```rust
// 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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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.