A .NET MAUI Android problem is easier to solve when you identify the failing stage. “It does not work on the phone” may describe a compile failure, packaging issue, installation rejection, startup crash, permission problem, or runtime behavior that differs from the emulator.

Start with classification: record the exact command or action, the first meaningful error, the device and Android version, and whether a minimal new MAUI application works in the same environment.

1. Verify the development environment

Confirm that the installed .NET SDK, MAUI workload, Android SDK, Java tooling, and IDE versions form a supported combination for the project. Run workload and SDK information commands and save the output with the issue. If the project recently changed target frameworks, compare the installed platforms with the target specified in the project file.

Do not begin by deleting every cache. First capture the failure. A clean rebuild is useful after you know which stage failed, but cleaning too early can remove evidence or produce a different error.

2. Separate device connectivity from application packaging

Use Android Debug Bridge to confirm that the device is visible and authorized. A device shown as unauthorized, offline, or absent is not an application bug. Check USB debugging, the connection mode, drivers, and the authorization prompt on the device.

If the device is connected, inspect whether an older application with the same package name was signed by another key. Android will reject an update signed with a different certificate. Uninstalling the old development build may solve the immediate problem, but production upgrades require consistent signing.

3. Capture the first startup exception

When installation succeeds but the application closes immediately, capture device logs from the moment of launch. Look for the first exception connected to the application package, not the longest chain of secondary messages. Common causes include missing initialization, unavailable services, invalid resources, dependency injection failures, and platform APIs called too early in the lifecycle.

Compare Debug and Release. Linker trimming, ahead-of-time compilation, configuration, and conditional code can produce release-only failures. If reflection or serialization is involved, verify that required types remain available after trimming.

4. Treat permissions as a runtime flow

Declaring a permission in the manifest is not always enough. Modern Android versions may require a runtime request and may split older permissions into more specific capabilities. Ask only when the feature is used, explain why it is needed, and handle denial without crashing.

RFID, barcode, Bluetooth, camera, files, notifications, and location-related features deserve special attention because their requirements vary across Android releases and device vendors.

5. Inspect paths, SQLite, and configuration

Desktop or emulator paths should not be copied into a device build. Use MAUI file-system locations for application data and verify that the database is created where expected. Log the resolved path during development. When shipping a starter SQLite database, confirm that it is copied as content and that the copy happens before the first connection.

Do not place secrets in the application package. Environment-specific API endpoints should be intentional, and the device must be able to reach the selected endpoint. A development server bound only to localhost is not reachable from a physical phone.

6. Isolate hardware SDK integrations

For RFID or barcode devices, first prove the application launches without the vendor SDK. Then initialize the reader in one service with explicit lifecycle handling. Log connection state, permissions, firmware information, and SDK errors. Avoid making a page constructor responsible for hardware startup.

Deployment checklist

  • Record SDK, workload, Android SDK, Java, IDE, device, and OS versions.
  • Classify the failure as build, package, install, launch, or runtime.
  • Confirm the device is connected and authorized.
  • Check package identity and signing consistency.
  • Capture the first relevant device exception.
  • Test runtime permissions on the target Android version.
  • Log application-data paths and endpoint configuration.
  • Add hardware SDKs only after the base application launches.

A disciplined checklist turns a broad deployment complaint into a small, testable hypothesis. That is usually faster than changing packages or project settings at random.