Skip to main content

Troubleshooting

Common issues and solutions when working with Openlynk.

iOS:

CauseFix
Associated Domains not configuredAdd applinks:YOUR_APP_SLUG.openlynk.to in Xcode → Signing & Capabilities
Bundle ID mismatchEnsure Xcode bundle ID matches the Openlynk dashboard exactly
AASA file inaccessibleVisit https://YOUR_APP_SLUG.openlynk.to/.well-known/apple-app-site-association — should return valid JSON
Stale AASA cacheDelete and reinstall the app — iOS caches AASA files for up to 24 hours
Testing in SimulatorUniversal Links don't work in the iOS Simulator — test on a real device
Testing from Safari URL barUniversal Links don't trigger from Safari's address bar — test from Notes or Messages

Android:

CauseFix
autoVerify not setAdd android:autoVerify="true" to the intent filter
Package name mismatchEnsure applicationId in build.gradle matches the dashboard
Wrong SHA-256 fingerprintVerify fingerprint matches your signing certificate
Asset links file inaccessibleVisit https://YOUR_APP_SLUG.openlynk.to/.well-known/assetlinks.json
Release vs debug fingerprintRelease builds use a different certificate — enter the release fingerprint in the dashboard
Google Play App SigningUse the App Signing key fingerprint from Google Play Console, not your upload key
tip

For step-by-step platform setup, see iOS Universal Links and Android App Links.

This is expected behavior. In-app browsers don't support Universal Links or App Links. Openlynk detects in-app browsers and shows an interstitial page with an "Open in Safari" or "Open in Chrome" button.

App opens but doesn't navigate to the right screen​

  • Verify handleIncomingURL (iOS) or handleIncomingUri (Android) is being called in your SceneDelegate/Activity
  • Check that your onDeepLink callback handles the destinationPath correctly
  • Add logging to see what ParsedDeepLink contains
  • Verify the link exists by checking the link details in the Openlynk dashboard
  • iOS: Ensure the release provisioning profile includes the Associated Domains entitlement
  • Android: The release certificate SHA-256 is different from debug. Enter the release fingerprint in the dashboard.
  • If using Google Play App Signing, the fingerprint in the dashboard must be the App Signing key from Google Play Console, not your upload key.

Deferred Deep Linking​

  • Ensure autoRestoreOnInit is true (or call restorePendingLinks manually)
  • Check that init() / initSDK() is called on app startup
  • If using email matching, ensure userEmailProvider returns the correct email
  • Pending links expire after 30 days — test with recently created links
  • Verify the pending link was stored by checking the dashboard analytics

Deferred matching uses multiple signals (email, fingerprint, IP, user-agent). If testing on a shared network, multiple devices might match the same pending link.

tip

For reliable matching, provide userEmailProvider so matching uses the user's email as the primary signal.

  • Ensure you passed metadata when creating the link
  • Check both parameters and metadata fields on the RestoredLink
  • The parameters field excludes internal keys (destination_path, destination_full, created_via). Use metadata for the complete data.
info

For details on how matching works, see How Deferred Deep Linking Works.

ErrorCauseFix
Network errorDevice is offline or API unreachableCheck internet connectivity
App not foundInvalid appIdVerify your appId from the dashboard settings
Invalid destinationDestination doesn't start with /Use paths like /product/123
Invalid API key / 401Wrong or revoked API keyGenerate a new key from the dashboard
HTTP 429Rate limitedImplement exponential backoff
HTTP 500Server errorRetry after a moment
  • Check that the baseURL is correct (default: https://openlynk.io)
  • Verify the app's slug is configured correctly in the dashboard

Push Notifications​

Device token not registering​

  • Ensure Firebase is initialized before calling registerPushToken
  • Check that the FCM token is not null or empty
  • Verify the appId is correct
  • Check the push notification stats in the dashboard to see if the device was registered

Push notifications not arriving​

  • Verify Firebase credentials are uploaded in the dashboard (app settings → Firebase Credentials)
  • Test the Firebase connection: app settings → Firebase Credentials → Test Connection
  • Check that the device token is registered (verify via push stats)
  • Ensure the app has notification permissions (especially iOS — call requestPermission())

Push notification doesn't navigate​

  • Ensure handlePushPayload is called when the push is tapped
  • Check that the push data contains destinationPath
  • Verify your onDeepLink callback handles the parsed destination correctly
info

For the full push notification setup guide, see Set Up Push Notifications.

Custom Domains​

Domain verification fails​

  • DNS propagation can take up to 48 hours — wait and try again
  • Verify your CNAME record: run dig links.mycompany.com and check it points to the CNAME target shown in your dashboard
  • Ensure the record type is CNAME (not A, unless using a root domain)

SSL certificate error​

SSL is provisioned automatically after domain verification. Wait a few minutes. If the error persists, re-verify the domain in the dashboard.

  • Ensure the domain is verified (check status in the dashboard)
  • Update your app's Associated Domains (iOS) and intent filter (Android) to include the custom domain
  • Verify .well-known files are accessible on the custom domain
info

For the full custom domain setup guide, see Set Up Custom Domains.

SDK Issues​

init() hangs or takes too long​

The restore API call runs during init. If the network is slow, init will be delayed.

Fix: Set autoRestoreOnInit: false and call restore manually after the app is fully loaded.

Memory leak warnings​

  • Flutter: Call dispose() when the widget is disposed — the SDK creates a stream subscription for deep links that must be cancelled
  • Android: Use singleTask launch mode to prevent multiple Activity instances
  • Ensure init() / initSDK() is only called once
  • Check that you're not creating multiple SDK instances
  • In Android, use android:launchMode="singleTask" to prevent multiple Activity instances

General​

How to find your App ID​

Dashboard → your app → the App ID is displayed on the app detail page.

How to find your API Key​

Dashboard → your app → SDK API Key card → click Generate if you haven't already. The key is shown only once — copy it immediately.

SDK returns 401 Unauthorized​

Your apiKey is invalid or revoked. Generate a new key from the dashboard. See SDK Authentication.

How to check your plan limits​

Dashboard → Settings → Billing → view current plan and usage. See Pricing and Plan Limits for a detailed comparison.

What's Next?​