Install an APK on Android and fix the “App not installed” error

You have built an app, tapped Download APK, and now there is a file on your phone or in your downloads folder. The next ten minutes decide whether your first tester says “nice” or “it says App not installed”. Android’s install flow is safe by design, which means it asks questions, blocks silently in a few cases and reports failures with a message that gives no reason. Every one of those failures has a two-minute fix once you know which it is.

This guide is written for people testing apps from App Builder Agent, but it applies to any APK. It covers the install path on a modern Android phone, what the Play Protect prompt means, the six causes of “App not installed” in the order they actually occur, and how to remove an old build cleanly so the new one goes on. Keep it open on a second device while you test.

What you need before you start

• The APK file — download it from the preview header on the phone itself if you can; it avoids the copy step. Files are typically 30–60 MB.
• Free storage — Android needs roughly three times the APK size free during install. Under 500 MB free is where installs start failing.
• Android 8 or newer — builds from the builder target modern Android; a phone from 2017 or later is fine.
• The package id — if you are replacing an earlier build, know whether the two came from the same project and build type. That single fact explains most failures.
• Two minutes of patience — the first install of an unknown app asks two or three questions. Later installs ask none.

Step by step: installing a test APK

1. Download the file on the phone. Open the builder in Chrome on the phone, sign in, open the project and tap Download APK in the preview header. Chrome asks whether to keep a file of this type; choose Download. On a computer, download it and send it to the phone through a USB cable, a cloud drive or a messaging app (send as a file, not as media).
2. Open it. Tap the download notification, or find the file in the Files app under Downloads. The package installer opens with the app name and icon.
3. Allow installs from this source. The first time, Android says “For your security, your phone is not allowed to install unknown apps from this source” with a Settings button. Tap it, switch on Allow from this source for Chrome (or Files, or the messaging app), and go back. The permission is per app, so you do it once for Chrome and once for Files.
4. Answer Play Protect. Google Play Protect may show “Unsafe app blocked” or “This app was built for an older version” or simply “Scan app?”. For a build of your own project, tap More details and then Install anyway, or Scan and wait a few seconds. This is Google noting that the app is not from the Play Store, not a fault it found.
5. Install and open. Tap Install, wait for “App installed”, then Open. Give it the permissions it asks for as you use it (camera, location, notifications) and note anything that behaved differently from the browser preview; tell the agent.
   On the real phone the keyboard covers the Notes field on the Add Expense screen and the Save button is hidden. Make the form scroll up when the keyboard opens, and move Save into the header.

If it fails: “App not installed” and other errors

• Same package id, different signature. The most common cause. A test APK from the builder is signed with the shared test key; a signed store build uses your project key. Android will not replace one with the other. Uninstall the existing app (hold the icon, App info, Uninstall), then install. Also happens when you install a build from a different project that reused the same package id.
• Corrupted or incomplete download. A file sent as an image through a chat app, a download interrupted at 97 %, or a file renamed to .zip and back will fail to parse. The installer says “There was a problem parsing the package”. Delete the file and download it again, on the phone if possible.
• Not enough storage. Android reports “App not installed” instead of telling you the disk is full. Check Settings, Storage; clear a couple of gigabytes (old WhatsApp media is the usual culprit) and retry.
• Android version too old. An APK built for Android 8 and above will refuse to install on Android 7 with the same vague message, or say “App not compatible”. Ask the agent whether the minimum Android version can be lowered; often it can, at the cost of one or two features.
• Install blocked by an admin or a work profile. Phones managed by a school or employer, and some carrier phones, block unknown sources entirely. Use a personal phone, or install into the personal profile rather than the work profile.
• “App not installed as package appears to be invalid”. Usually a mismatch between the phone’s CPU architecture and the build, or an APK from a broken build. Rebuild from the builder; a fresh test APK fixes this almost every time.
• Installed, but the icon is missing. Some launchers hide new apps until the drawer refreshes. Search for the app name from the home screen, or restart the launcher.

Uninstall the old version cleanly

When two builds conflict, removing the old one is the fix, and it takes ten seconds. Hold the app icon, tap App info (or the small “i”), then Uninstall. If the app is not on the home screen, go to Settings, Apps, find it by name, and uninstall from there. On-device data (AsyncStorage or the SQLite file) is removed with the app; if a tester has data worth keeping, ask the agent for an export or backup button first.

Prompts that work well

Common mistakes (and the fix)

• Sending the APK as a photo or in a group chat. Chat apps compress media and sometimes strip extensions. Send it as a document, or share a download link.
• Allowing unknown sources for the wrong app. The setting is per source. If you downloaded with Chrome, allow Chrome; if you opened it from Files, allow Files.
• Tapping Cancel on Play Protect. The install quietly stops with no error. Reopen the file and choose Install anyway.
• Testing a store build over a test build. Uninstall between the two; the signatures differ by design.
• Ignoring the phone’s storage. A full phone fails installs and also crashes apps that write files. Free space before blaming the build.
• Not reading the exact message. “Problem parsing the package” means the file; “App not installed” usually means the signature or storage. The wording points at the cause.

Make it feel finished

• A short install note sent with the APK: file size, “Allow from this source” and “Install anyway” in two lines.
• A version number on the Settings screen so testers can tell builds apart.
• A “What’s new” message on first launch after an update.
• Notification permission requested when it is needed, not on the first screen; Android 13 and later show a prompt.
• A download page on the published website with a QR code, so testers can install from any phone without a chat app.

Installing, publishing and next steps

Once the test APK installs and runs on two or three phones, the next step is a signed build with your own package id and version for Google Play; the signed APK and AAB guide covers the identity, the key and the Play Console forms. If the icon or name is still the default, fix it before screenshots with the icon and name guide. The APK app builder page lists what the free and paid builds include.

A calculator or converter is the classic first APK because it needs no permissions and installs everywhere; the ready-made calculator apps show what a clean one looks like. Open the builder, describe yours, and you can be installing it on a phone within a few minutes.

Frequently asked