# Troubleshooting

> The common problems, in the order people hit them.

Source: https://straitlink.in/docs/troubleshooting/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## The link opens the browser instead of the app

This almost always means the phone couldn't verify that your app may open links on your domain.

Start with the free [App Links checker](https://straitlink.in/tools/app-links-checker/): it fetches both files from your domain and explains what's wrong with them (missing file, redirect, wrong content type, malformed fingerprint or app ID).

1. **Check the file.** `curl https://hilltop.strait.link/.well-known/assetlinks.json` should list your package name and fingerprints. A `404` means the Android fields in Apps & stores are empty.
2. **Check the SHA-256.** The fingerprint must match the certificate of the build on the phone:
   - Debug builds: your debug keystore.
   - Release builds you install yourself: your upload key.
   - Builds from Google Play: the **App signing key** in Play Console → App integrity. This is Google's key, not yours.
3. **Check the intent filter**: `android:autoVerify="true"`, `https` scheme, and `android:host="hilltop.strait.link"` exactly.
4. **Re-verify.** Android checks at install time. Reinstall the app, then run `adb shell pm get-app-links com.yourco.app`. You want `verified`.
5. **Tap, don't type.** Pasting a link into the address bar never opens an app. Test from Messages, WhatsApp or Gmail.

To test one link's path against your files and get the exact `adb` (Android) or `xcrun` (iPhone simulator) command that opens it, use the free [deep link tester](https://straitlink.in/tools/deep-link-tester/).

Still failing? [Android App Links verification failed](https://straitlink.in/blog/android-app-links-verification-failed/) explains each state `get-app-links` prints and the causes behind it.

On iPhone: check `apple-app-site-association` lists `<Team ID>.<bundle ID>`, and the app has `applinks:hilltop.strait.link` in Associated Domains. iOS caches the file through Apple's CDN, so changes can take a while to show. [Universal Links not opening: 12 causes](https://straitlink.in/blog/universal-links-not-opening-causes/) goes through the rest, from how the link was tapped to your app delegate.

## Samsung Internet

When the person taps a link on a page in Samsung Internet, it handles our hand-off like Chrome: if the app is installed it opens; if not, it goes to Google Play. When an unverified link is handed to Samsung Internet from another app (an SMS or email app), there's no tap inside the browser, and in our real-phone test (Samsung Internet 30, 3 October 2026) it went to Google Play even though the app was installed. Verified App Links avoid this, because Android opens the app before any browser runs ([details](https://straitlink.in/blog/samsung-internet-intent-link-opens-play-store/)). If Samsung Internet keeps opening links in the browser, check **Settings → Useful features → Open links in other apps** is on.

## Firefox and Edge ask before opening the app

Firefox ("Open this link in …?") and Edge ("wants to open an external app") show a confirmation before handing a link to an app. That's the browser's choice and can't be skipped. Once the person confirms, the app opens on the right screen and the tap is counted once.

## In-app browsers (Instagram, TikTok, X, Facebook…)

In-app browsers often don't open apps or app stores from a link on their own, so a deep link may not work inside them. We detect them and show a page made for them: on Android an **Open in app** button, and everywhere steps to open the link in the real browser, where it works normally. To skip that step, share links where possible in places that hand them to the phone's browser or app, for example Messages.

## The deferred link didn't open the right screen after install

- **Android**: the app must be installed **from Google Play** (internal testing is fine). Sideloaded builds have no install referrer. In Settings, set "When someone without the app taps a link" to **Always Google Play** while your app isn't public, otherwise we send people to your website to avoid Play's "Item not found" page.
- **iPhone (opt-in)**: device matching must be on in Settings → iPhone installs, and the person must tap **Get the app** on our page in Safari, and open the app within an hour, on the same network. A different network (Wi-Fi to cellular) will usually prevent a match.
- **Both**: the deferred check runs once per install. Uninstall and reinstall to test again.

## The app opened but `matched` is false

Check `reason` on the link event:

| Reason | What it means |
|---|---|
| `not_found` | No such link in this workspace (check the publishable key and the slug) |
| `expired` | The link's expiry has passed |
| `password_protected` | Password links can't be opened directly in the app |
| `no_match` | Deferred: no recent matching tap |
| `network` | The phone couldn't reach us. The open is saved and reported later |
| `invalid_url` | The URL couldn't be parsed |

## Still stuck?

Email [support@straitlink.in](mailto:support@straitlink.in) with the link, the phone model, the browser or app you tapped it in, and what happened. Or message us on WhatsApp: [+91 81218 61890](https://wa.me/918121861890).
