Troubleshooting

Find what you're seeing below, grouped by when it happens. Errors the SDK reports while your app runs, such as permission_denied, are covered in Handling errors.

While building your app

Gradle can't find io.captur3d:roomio-sdk

Your project is missing the Maven repository that hosts the SDK. Add https://cdn.roomio.io/sdk/android/maven as shown in Manual installation:

• Android: in settings.gradle.kts.
• React Native: in android/build.gradle.
• Expo: the Roomio plugin adds it for you, so check that @roomio/react-native-sdk is in your app config's plugins, then run npx expo prebuild --clean.

Gradle fails before compiling anything

For example with IllegalArgumentException: 26.0.1. Gradle is running on a newer Java than it supports. Point JAVA_HOME at JDK 17 or 21, such as the one bundled with Android Studio.

Xcode says the package requires iOS 17

Your app's Minimum Deployments is below 17.0. Raise it to 17.0 or later. In React Native, also set platform :ios, '17.0' in ios/Podfile; in Expo, set ios.deploymentTarget to "17.0" in your app config.

Expo Go shows a red screen

Expo Go can't run the SDK's native code. Use a development build: npx expo run:ios, npx expo run:android or EAS Build.

When your app runs

publishable_key_rejected in the device log

Roomio didn't recognise your publishable key: it's mistyped, cut short, or from another account. Copy it again from Developers → API keys in the Roomio portal; it starts with roomio_pub_live_. Until you fix it, a new install or an app update can't scan: startScan throws publishable_key_rejected.

startScan throws connection_required

The app hasn't been online since it was installed or updated. Roomio sets up scanning the first time the app has a connection, usually within seconds of launch. Ask the user to connect, then try again. After that, scanning works offline.

startScan throws sdk_update_required

Roomio no longer supports the version of the SDK in your app, usually because of a security fix. Update to the latest release, ship an app update, and ask your users to install it. Scans from that version also come back as scan.failed.

The scan button never shows

isSupported says the device can't scan. That's expected on the Simulator and emulators, iPhones below iOS 17, 32-bit Android phones, and Android phones without ARCore support. Try a different phone.

After the scan

Your backend receives scan.failed

Roomio couldn't use the bundle at the bundle_url you sent. Either:

• Roomio couldn't download it. The link must be https and work without a login or header. Roomio downloads the bundle in the background after your call, so a presigned URL that expires within minutes can run out first.
• The file was changed after export, for example re-zipped, or uploaded as form fields instead of the file itself. Upload the file exactly as export() wrote it. See Export and upload.

Fix the cause and send the scan again.

Scans from your Android app come back as scan.failed

Android is in beta. You can build and test your Android integration, but Roomio doesn't process Android scans yet. Processing is coming in the next few weeks. Until then, test end to end with an iOS build.

Still stuck?

Email support@roomio.io with a diagnostics file, the scanId, the SDK version and what you expected to happen.