Troubleshooting and limits

Start with the preview. In the link builder, Test on phone shows the route a link would take on a phone without recording a click. It shows the platform, the kind of browser, and the outcome.

A link opens the browser instead of the app

1. Open the domain (Smart Links > Domains), choose App files and select Check association. Every check should read Passing for both hosts.
2. If an app says Needs setup, add the Apple Team ID (iOS) or the SHA-256 fingerprint (Android) in Connect > Apps. Use Fix in Apps.
3. Confirm the app contains both hosts: the Associated Domains entitlement on iOS, the intent filter with android:autoVerify="true" on Android. A build made before you added them does not work.
4. On iOS, typing the link into the Safari address bar never opens an app. Tap it from Notes, Messages or an email. Apple caches the association file for up to 24 hours, so a fix may not show at once.
5. Check the template. If When the app is installed is Treat as not installed, the link never opens the app.
6. If the person is in an in-app browser such as Instagram, the Landing page is shown when it is on. Its button opens the link on the alternate host. Check the alternate host is in your app too.

See Deep links and deferred deep links.

The app opens but not on the right screen

• Your app decides what to do with the deep link value. Log the onDeepLink payload and check deepLinkValue.
• Call handleIntent (Android) or handle(userActivity:) (iOS) on every launch path. An app that is already running receives the link in onNewIntent or the scene callbacks.
• Register the listener early. A link that arrives first is held and delivered when you attach it.
• A rule can change the deep link value. Check the link's Rules tab and the template's Rules.

Installs are not credited to a link

• Check the SDK version. Deep link matching needs 0.4.0 or later.
• Check Smart Links > Settings > Match rate. A low iOS rate means the match window is short or the strictness is too high. Try a longer window, or Balanced instead of Strict. Lenient credits more installs and some of them wrongly.
• On Android, the match is exact when the link sent the person to Google Play. A link sent to a Third-party store or URL cannot be matched.
• Tracking opted out in the app means no link calls are made.
• Test and Live do not mix. A Test build never matches a Live click.
• A person who clicked a link long before installing is outside the window (iOS 15 to 240 minutes, Android 1 to 30 days).

A domain stays Pending DNS or shows an error

See the table in Link domains. In short: publish both the TXT and the CNAME at the exact host names the card shows, turn off any proxy that hides the CNAME, and use Check now.

A link shows "not found", "expired" or goes to the wrong place

• The short id is wrong or archived. Short ids on a case-sensitive domain must match case.
• The link is paused, archived, past its date or past its click limit. It uses the template's Expired or paused link target.
• A rule matched. The link's Overview shows which rule decided clicks.
• The domain has Dynamic links off, and the path is not a saved link.
• The domain is suspended. Only an Owner can unsuspend it.

I cannot save a web address

Redirect addresses must be https and on the redirect allowlist (Smart Links > Settings > Redirect allowlist). The form says which one failed. For a host and its subdomains use *.example.com.

The short id cannot change

A short id locks after the first human click so shared links never break. Duplicate the link to get a new one.

A template will not archive

You cannot archive the default template of a domain, or a template that links still use. Choose another default, or move the links first.

Webhook problems

• Failing: your server must answer with a 2xx status within 8 seconds. Use Send test to see the answer.
• After 24 hours of continuous failure the webhook turns itself off. Fix the server, then Turn on.
• Your server sees the same deliveryId again after a retry. Ignore duplicates.

FAQ

Do smart links work in Test? Yes. Test and Live have separate domains, links, clicks and matches. Test traffic never reaches Live data.

Can I use one domain for several apps? A workspace has one app per platform, and a domain's templates use them. Use several templates on one domain for different routing.

Can I export the people who clicked? No. Analytics and the CSV hold counts only.

Can I use a 301 redirect? No. Every redirect is a 302 so links can be edited later.

Do bots count? No. Link previews and known bots get a preview page and are not counted as clicks. The click webhook still reports them, flagged isBot.

What happens to a printed QR code if I pause the link? It sends people to the template's expired target until you resume it.

Limits

Item	Limit
Short id	3 to 40 letters, digits, - or _, unique per domain
Shared subdomain	3 to 32 lowercase letters, numbers or hyphens
Generated short id length	4, 6, 8, 10 or 12 (links made in your app: at least 8)
Tags per link	10, each up to 30 characters
Rules per link or template	20
Redirect allowlist	50 hosts
Branding messages	140 characters
QR label	40 characters, margin 2 to 8 modules, logo 15 to 30 percent
CSV import	10,000 rows, 5 MB
Links created in the app: deepLinkValue	512 characters
Links created in the app: params	10 entries, keys up to 40 characters, values up to 256
Links created in the app: daily limit	1 to 1,000 per person (default 50)
iOS match window	15 to 240 minutes (default 60)
Android match window	1 to 30 days (default 7)
Click retention	30 to 400 days
Webhook events per request	100
Test on phone code	Valid for 15 minutes

Related pages

• Link domains
• Routing and rules
• Link settings