Link Doctor

A link that does not open the app fails silently. There is no error, nothing in your logs, and the two platforms fail in different ways for different reasons. Link Doctor looks at your domain from the outside, exactly as Apple and Google look at it, and reports what is wrong with the fix for each thing it finds.

It needs no account, no SDK and no key, and it works on any domain whether or not Vouch hosts it.

The web tool

vouch.dev/link-doctor takes a domain and, optionally, the identities of your apps:

The report leads with one sentence, then the findings, each with its fix, then exactly what was fetched for each platform: status, content type, whether a redirect happened, and what the file declares.

The CLI

vouch-doctor is a single Go binary that runs the same checks locally. It talks to no service of ours unless you point it at one, so it works on a laptop with no network access to Vouch and on a build machine with no credentials.

go install github.com/vouch-dev/vouch/services/vouchd/cmd/vouch-doctor@latest

vouch-doctor check --host links.example.com \
  --bundle-id app.roam.ios --team-id ABCDE12345 \
  --package app.roam --fingerprint A1:B2:C3:...

Flags

Reading identities out of a build

Given a build, vouch-doctor reads what the binary actually claims rather than what you told it:

• --ipa takes the team ID, the bundle identifier and the applinks: domains from the entitlements in the embedded provisioning profile.
• --apk takes the package name and the autoVerify intent filters from the binary manifest, and the SHA-256 fingerprint from the signing certificate in META-INF.
• --aab takes the same from the protobuf manifest.

Exit codes

A 2 is not a verdict on your domain. It means nothing was checked.

In CI

Run it after the build, against the artefact you are about to ship, and a release that would break links fails before it reaches anyone. In a GitHub Actions workflow:

- name: Check deep links
  run: |
    go install github.com/vouch-dev/vouch/services/vouchd/cmd/vouch-doctor@latest
    vouch-doctor check --host links.example.com \
      --aab build/app-release.aab \
      --path /posts/123 --path /invite/abc \
      --warnings-as-errors

Use --json when something else needs to read the result. Finding codes are stable, so a script can branch on them.

The API

Both surfaces call one endpoint. It is public and needs no authentication, and it is rate limited by address:

curl -X POST https://api.vouch.dev/v1/doctor \
  -H "Content-Type: application/json" \
  -d '{"host":"links.example.com",
       "bundle_id":"app.roam.ios","team_id":"ABCDE12345",
       "android_package":"app.roam","paths":["/posts/123"]}'

The report carries summary, ok, findings, and an apple and google block holding what was actually fetched: status, content_type, redirected, declared, fingerprints and patterns. Every finding carries code, severity, platform, title, detail, fix and often docs.

What each check means

Severity, and why iOS is judged differently

An error means links are broken now. A warning means they will break, or are fragile.

That distinction is why a fault in how your server delivers the Apple file drops to a warning when Apple's mirror is holding a good copy: iOS devices read the mirror, not your server, so those links open today. It still needs fixing, because the mirror re-fetches from your server and that fetch is what will hit the fault. Android has no mirror, so the same fault there is an error.

The three questions people ask when they leave Firebase

Why does the link open the browser instead of the app? Almost always the association file: a redirect, a 404 on the apex, the wrong content type, or a path pattern that does not cover the URL. The report names which.

Which fingerprint goes in assetlinks.json? The SHA-256 of the app signing certificate, the one Play Console shows under App signing, not your upload key. --aab reads the right one straight out of the build.

Why does it work on Android but not iOS? The two platforms read different files, with different path rules, and iOS reads through Apple's CDN rather than your server. A fix that is live on your server can still be missing from the copy the phone sees.

See also Domains and association files for the hourly check that runs against every registered domain, and Migrating from Firebase Dynamic Links.