Skip to main content
Each entry names the symptom you see, the usual cause, and what to do. To contact NEUROFIT, see Diagnostics and support.

Activation and license

The reason names the check that failed: the key is malformed or does not verify, it does not cover this app’s identifier, or this SDK build is newer than the key. Each has its fix in reasons and fixes. Apps you have already shipped keep working.
The key does not list this app’s identifier. This debug build accepts it, and release builds refuse it with licenseInvalid. Ask NEUROFIT for a key that lists the identifier, compared exactly and case-sensitively, before you ship (Debug builds).
The app carries a trial key whose end has passed (Trial keys). The end is checked against the device clock, so if it should not have passed yet, check the device’s date and time. Otherwise ship your paid key, or a longer trial key, in an app update. The pre-built flow shows its unavailable screen and ends with onError (licenseInvalid).
activate was not called, or it threw and the error was swallowed. Activate once at launch and log the outcome. start() rechecks activation, so it throws the same error if activation never happened.

Permissions and camera

Camera access is not granted: never asked, denied, or blocked by a device policy. start() never prompts, so call requestCameraPermission() first (Starting a session). After a refusal, explain why the reading needs the camera and link to Settings (UIApplication.openSettingsURLString, Settings.ACTION_APPLICATION_DETAILS_SETTINGS). iOS asks only once, so afterwards requestCameraPermission() returns false at once. On Android a second refusal may be permanent, so check shouldShowRequestPermissionRationale first. Call start() again once access is granted.
The activity that asked was recreated while the system dialog showed (a rotation, a split-screen resize), which loses the callback. Lock the screen that asks, and check hasCameraPermission in onResume (caveat).
Another app holds the camera, or the camera failed to open, stalled twice, or could not be restored after an interruption. It always arrives as the failed event, on both platforms, never from start(). Retry after a moment with a new session (start() again in the wrappers). On Android the SDK binds only its own CameraX use cases, but release a camera you hold yourself before a reading.
Check hasTorch: devices without one read in room light (Device support). On a phone with a torch, close other apps that may hold the flash, and let the phone cool down (iOS disables the torch when the device is hot).
The app left the foreground, another app took the camera, or on iOS a phone call, Split View or a media-services reset. The session does not fail: positioning resumes by itself when the cause clears. If the camera cannot be restored within 10 seconds once the app is back, the session ends with cameraUnavailable (Interruptions).
This should not happen: the SDK clears the camera settings it applied before it unbinds. Make sure the session’s stop() ran (it is idempotent, so call it from your screen’s teardown), and send NEUROFIT the device model.

Positioning never starts the reading

The camera does not see a fingertip: the finger is over the wrong lens (phones with several rear cameras use the main wide camera), a thick case or lens protector is in the way, or the torch is off. A small camera preview lets the user see the red glow when the finger is placed right.
The pulse is faint. Cold hands are the usual cause, and pressing hard is the second (it squeezes the blood out of the fingertip). A thick case can also weaken the signal. This value is reported on iOS only for now.
The signal is there but not steady: the finger is moving, the pressure keeps changing, or the phone is held in the air with a tense arm. Rest the phone on a table or the lap and hold the finger still.
The camera cannot hold its frame rate, and no reading starts while it shows. On iOS this is almost always Low Power Mode, on Android Battery Saver or thermal throttling. The session never fails for a low frame rate. Ask the user to turn them off (the flow’s guidanceLowFrameRate). A very old or slow device can also cause it.
Check the hold (isAutoStartEnabled, setAutoStartEnabled in the wrappers). While it is false, positioning goes on and the start progress fills, but no reading starts. Set it back to true when your screen is ready. In the wrappers the hold goes back to true when a session ends (Holding the start).
Some Android cameras take longer to settle before a reading can start. This is expected. Show the steady guidance and the start progress so the wait is visible.
cancelReading() applies only while measuring. While positioning there is no attempt to cancel. Use stop() to leave the screen.

The reading keeps restarting

The finger lifted or slid for a few seconds. Ask the user to keep the fingertip resting on the lens for the whole minute, and to avoid talking or adjusting their grip.
The signal stayed too poor to finish a reliable reading, so the session stopped early rather than run to 60 seconds for no result. Movement, changing pressure, cold fingers and hard pressure are the usual causes, and a device with weak optics under a thick case is another. Rest the phone on a table, warm the hands and use a lighter touch. LivePreview.signalQuality drops before this cancel, so you can show it as an early cue.
The SDK restarted the camera during a reading: after a stall, or on iOS to adjust the capture when the camera could not hold its frame rate. The attempt starts again by itself. If it keeps happening on iOS, ask the user to turn off Low Power Mode. A second stall in one session ends it with cameraUnavailable. If a device model does this consistently, send NEUROFIT the model.

Results

The full minute was captured but did not pass the quality check, so there are no numbers, and the next reading starts by itself. A reading where no heart rate was found ends the same way, usually because the fingertip did not fully cover the lens, so a visible preview helps. Show the flow’s noticeQualityCheckFailed. To pause after a few in a row, see pause after failed checks. If one device model fails it across users, tell NEUROFIT.
The live HRV (RMSSD) is provisional and appears from about 20 s into an attempt. Every cancel restarts the clock.
Expected. The live value comes from a recent window and updates as it goes, while the final value uses the whole minute with the full quality checks. Always store the final value.
Both are optional. sd2sd1 is absent when its expression is undefined for the reading, and baevskyStressIndex when it could not be computed (Metrics). rmssdMs and sdnnMs are always present.
Wearables report nightly or multi-hour averages, and a seated daytime reading is a different moment. RMSSD is also strongly affected by breathing (slow breathing raises it). Compare like with like: a morning seated reading with the previous morning seated reading (Outcomes best practices).

Build and integration

The download token is missing, in the wrong file, or revoked. Set it up on every machine and CI job that builds the app (Download token): ~/.gradle/gradle.properties, ~/.netrc (with chmod 600), NEUROFIT_DOWNLOAD_TOKEN for npm and Yarn, or dart pub token add. If it still fails, ask NEUROFIT for a new token.
A cached download is stale. In Xcode, choose File > Packages > Reset Package Caches, then resolve again.
The binary needs the Xcode version releases are built with, or newer (Requirements).
Add the NeurofitVitals product, and NeurofitVitalsUI for the pre-built flow, to the target that imports it (General > Frameworks, Libraries, and Embedded Content). Source builds: Install from source or manually.
Native apps: add the neurofit repository with its credentials to settings.gradle.kts (Android quickstart).React Native, Flutter and Capacitor: the package carries the SDK in its android/maven folder and adds it to your Android build. If android/settings.gradle sets repositoriesMode to PREFER_SETTINGS or FAIL_ON_PROJECT_REPOS, Gradle ignores or rejects that repository, so list the folder there:
android/settings.gradle
Capacitor 8 cannot build with FAIL_ON_PROJECT_REPOS, because its own Android modules declare repositories.
A calling mistake, named by the message. start() must be called on the main thread (Android): call it from the main thread, for example in lifecycleScope. The session is already running: call stop() first. A finished or stopped session: create a new one (in the wrappers, start() does).
The AAR ships consumer-rules.pro, which keeps the public API in com.neurofit.vitals.* (the top-level package only, everything else is internal and meant to be shrunk). If your R8 configuration ignores consumer rules, copy the rules on the Android API reference.
A hot reload can leave a native session running with no JavaScript or Dart listener. Call stop() in your cleanup, and start() again when the screen mounts.

Diagnostics and support

The SDK sends nothing anywhere, so NEUROFIT cannot look a reading up. What your app records is what support works from.

What to record

Keep these with each reading attempt, in your own logs or analytics: None of this contains health values beyond the result you already store, and none of it identifies the user. To find patterns across users: Measuring reliability in a pilot.

Contacting support

Write to contact@neurofit.app with:
  • the SDK version, the platform and OS version, and the device model
  • the reading id and completion time, when the question is about a result
  • the events you recorded for the attempt: the guidance that kept showing, the cancel reasons, the error
  • what the user did, if you know it (seated or moving, phone on a table or in the hand, which finger)