Troubleshooting

Start with alphyn-cli doctor; it diagnoses the integration and reports an honest pass/fail for each part, which usually points straight at the problem. Repair a failing integration by re-running alphyn-cli integrate.

”could not determine platform”

The CLI detects the platform from the project in the current directory. Run it from your project’s root, or, for a new project, start with alphyn-cli new <platform>.

Authentication errors (401 / invalid key)

Confirm the API key is correct and active for this app in the Alphyn dashboard, and that it is passed via its per-platform flag: --android-api-key for the Android app, --ios-api-key for the iOS app (or their -file forms; the CLI reads no environment variable). A key generated for a different app is rejected. On a cross-platform project make sure each platform uses its own app’s key: the Android build registers with the Android app’s key and the iOS archive with the iOS app’s key, and the backend rejects a registration made with the other platform’s key.

Registry resolution fails at build (401 or “could not resolve” the SDK)

The SDK’s native binaries resolve from the Alphyn package registry when your app builds, so a build that cannot authenticate fails at dependency resolution (Gradle), at swift package resolve (native iOS), or at pod install (Flutter and React Native iOS), typically with a 401 or a “could not find/resolve” error for com.byterialab:alphyn-sdk or Alphyn.xcframework.

• Android, Flutter, React Native, Unity: export ALPHYN_REGISTRY_KEY (your app API key) in the build environment before building. On Unity, also enable Custom Main Gradle Template in Player Settings > Publishing Settings so the wired mainTemplate.gradle is used.

• Native iOS: add the ~/.netrc entry alphyn-cli integrate printed, then resolve packages in Xcode:

  machine packages.byterialab.com login x password <YOUR_APP_API_KEY>

• A wrong or inactive key is rejected with a 401; confirm the key is active for this app in the dashboard. The registry credential and the build-registration key are the same app API key used two ways, so a key that registers builds also resolves the SDK.

See SDK Registry Access.

Build reported as not registered / not enrolled

If a build prints a non-blocking “build hash NOT registered” warning, or doctor reports the build is not enrolled, the register hook could not find the API key. integrate with your key flags provisions a gitignored .alphyn/<platform>-api.key file that the hook reads automatically; if it is missing (for example the build runs on a machine or CI where integrate was not run), either re-run integrate, or point the override at a key file: alphyn.api.key.file (Gradle), ALPHYN_ANDROID_API_KEY_FILE (Unity), or ALPHYN_IOS_API_KEY_FILE (the Xcode archive). On a cross-platform project also provision the iOS key with --ios-api-key. doctor names the exact key path it expects. A registration hook never fails the build; it degrades to this warning so an unregistered build fails closed at launch instead.

The app closes immediately on an emulator or simulator

This is expected security behavior, not an integration error. The SDK’s runtime device-integrity scanning flags emulators, simulators, rooted or jailbroken devices, debuggers, and hooking tools according to your app’s ruleset in the Alphyn dashboard, and terminates the app (fail-closed) when a rule your ruleset treats as blocking is triggered. A correctly integrated, registered build will still close on launch on an emulator or simulator if your ruleset blocks that environment.

To develop or test on an emulator or simulator, allow it in your app’s ruleset in the dashboard (relax or disable the emulator/simulator rule for your development app), or test on a physical device. If alphyn-cli doctor reports the integration healthy and the build is registered but the app still closes at launch on an emulator/simulator, the ruleset is the cause.

Ruleset availability: your ruleset applies once the SDK has retrieved it from the Alphyn backend. If the SDK cannot retrieve it on a given launch, in practice the first launch after install, before it has ever reached the backend, it falls back to a strict built-in default in which every detection is blocking, and a device that trips any detection is terminated even when your ruleset would allow that device. Once the ruleset has been retrieved the SDK retains it, and later launches apply your ruleset with or without connectivity. Give the first launch after install working connectivity to the Alphyn backend; on a device that trips no detection this makes no difference either way.

macOS blocks the binary on first run

The macOS binaries are checksummed but not yet Apple-notarized. After verifying the SHA-256, clear the quarantine attribute or approve the binary once. See Installation.

Android: Play App Signing

The value the SDK reports for integrity is the signing certificate’s SHA-256, and the build hook registers the certificate of the artifact it just built. That is the correct value for a self-signed or upload-key-only build.

It is the wrong value when the app ships through Play App Signing. There, Google re-signs your upload with its app-signing key, so the app your users install is signed by a certificate that does not exist on your machine and cannot be derived from your artifact. The hook enrolls your upload certificate, the installed app reports Google’s, the two never match, and every Play install is rejected - while alphyn-cli doctor still reports the local build as enrolled, because the local build genuinely is.

Enroll Google’s certificate once, by hand:

alphyn-cli register --android-api-key <key> --apk <path/to/apk> \
    --play-cert <SHA-256 from the Play Console>

Find the value in Play Console → Test and release → App integrity → App signing key certificate → SHA-256 certificate fingerprint. Paste it as shown: the colon-separated, upper-case form is accepted and normalized.

This is a one-off. The signing certificate is stable across releases, so later builds need nothing. The hook may keep enrolling your upload certificate alongside it; that is harmless, because enrollment is a set and both values stay registered.

alphyn-cli doctor raises this as an advisory whenever it inspects a release artifact. It cannot detect Play App Signing from a local file, so it asks rather than asserts.

The SDK seems out of date

Run alphyn-cli sdk update --android-api-key <key> to remove the installed SDK and re-install the latest version, then alphyn-cli doctor to confirm.