Install Errors

When Board rejects an install, it returns a machine-readable error code and a message:

  • The Board Connect web UI shows both in the failure dialog.
  • The board-connect CLI prints them as [code] message, for example [validation_failed] missing Board SDK native library.
  • The HTTP API returns them as JSON: {"error": "<code>", "message": "..."}.

Find your code below. When you ask for help, include the exact [code] message line and the file name you installed.

APK installs

validation_failed

The file is a readable APK, but it is not a valid Board app. The message says which check failed:

  • missing Board SDK native library: The APK does not include the Board SDK. In Unity, make sure the SDK package is installed in Package Manager before you build. Follow the Unity Quick Start or the Godot Quick Start.
  • forbidden permission: The APK requests a permission Board apps cannot hold, such as SYSTEM_ALERT_WINDOW, QUERY_ALL_PACKAGES, or install/delete-package permissions. Remove it from your manifest.
  • forbidden service / forbidden receiver: Accessibility services, input methods, and device-admin components are not allowed. Remove the component.
  • forbidden intent filter: Apps that declare launcher or dock intent categories (HOME, CAR_DOCK, DESK_DOCK) are not allowed. Remove the category.

invalid_apk

The file could not be parsed as an APK. Rebuild and install the fresh output. If you renamed another file type to .apk, install the real build artifact instead.

install_failed

Validation passed, but Android could not install the APK. The message is Android’s own reason. Common ones:

  • INSTALL_FAILED_NO_MATCHING_ABIS: The APK has no arm64 native code. In Unity, set the scripting backend to IL2CPP and check the ARM64 target architecture in Player Settings, as described in Build & Deploy.
  • INSTALL_FAILED_VERSION_DOWNGRADE: A newer build of the same package is already installed. Uninstall it first, or raise your version code.
  • INSTALL_FAILED_UPDATE_INCOMPATIBLE: An installed build of the same package is signed with a different key. Uninstall it first.
  • INSTALL_FAILED_INSUFFICIENT_STORAGE: Board is out of space. Uninstall apps you no longer need.

no_launcher

The APK has no launchable activity, so Board would have no way to start it. Declare a launcher activity in your manifest.

concurrent_install

Another install of the same package is already running. Wait for it to finish, then retry.

Web app bundles

no_sdk

The bundle’s code never references the Board SDK. Build your app against @board.fun/web-sdk and repack.

missing_config

The bundle has no harness-config.json. Pack your built app with board-pack, which generates one. See Build & Deploy.

missing_entry

harness-config.json names an entry file that is not in the zip. Repack from a complete build output.

invalid_app_id

The appId in harness-config.json must be a canonical UUID. board-pack generates a stable one for you.

invalid_bundle

The file could not be read as a zip. Repack with board-pack rather than zipping by hand.

webapp_install_failed

Board could not install the web app for a reason outside the checks above. Retry once; if it persists, treat it like internal.

browser_unavailable

The component that hosts web apps on Board did not respond. Reboot Board and retry.

Uploads

unrecognized_bundle

The file is neither an APK (AndroidManifest.xml) nor a packed web app bundle (harness-config.json). Install the build artifact your SDK’s deploy guide produces.

ambiguous_bundle

The bundle contains both AndroidManifest.xml and harness-config.json, so Board cannot tell which kind of app it is. Ship one or the other.

incomplete_transfer

The upload ended before the whole file arrived. Check your network connection and retry.

Other

internal

Something unexpected failed on Board. This is not something you can fix in your bundle:

  1. Reboot Board and retry the install.
  2. If it keeps failing, contact support with the [internal] line, the file name, and your Board OS version (Settings > About).