The 18-Character URL Limit That Broke a Mobile App's Deep Links
Archi4 min read
Contents
The 18-Character URL Limit That Broke a Mobile App's Deep Links#
Q: What was the smallest detail that mattered most in your recent app release?
A: It was the length of a custom URL scheme. We had been using a scheme called companionapp (12 characters). When we rebranded to sidekickcompanion (18 characters), deep links from email and web suddenly stopped working on Android 11 and later. The OS has a limit on the number of characters for a scheme, and we were right at the edge. One character over, and the link handler would silently drop the intent.
Q: How did you discover it?
A: A support ticket came in: "Password reset link does nothing." We reproduced it on a Pixel 4 running Android 11. The link opened the app, but the reset screen never appeared. Logcat showed ActivityNotFoundException for the intent, but only when the scheme was 18 characters. At 17, it worked. We spent two days thinking it was a server issue before we isolated the string length.
Q: Why does the scheme length matter?
A: Android's intent resolution has a limit on the total length of the URI, but the scheme itself is also validated against a pattern. The pattern allows letters, digits, and a few symbols, but the total scheme length is capped at 18 characters in some code paths. This is not well documented. Most developers never hit it because they use short schemes like myapp or fb. We hit it because we chose a long brand name.
Q: What was the fix?
A: We switched to a 9-character scheme, skcompanion, and kept the old one as an alias for backward compatibility. We also added a unit test that asserts the scheme length is under 16 characters. The fix took ten minutes. The investigation took two days.
The Cost of a Small Oversight#
Q: How many users were affected?
A: About 12,000 users on Android 11 and 12 who clicked a reset link in a 36-hour window. We estimate 3,000 of them gave up and contacted support. The rest likely requested a new link or used the app's in-app reset flow. The churn was small but measurable: our daily active users dipped by 0.4% for three days.
Q: What did you learn about testing?
A: Our test suite covered deep links, but only with the old scheme. When we rebranded, we updated the scheme in code but not in the test fixtures. The tests passed because they used the old string. Now we generate the scheme from a single constant and assert its length in a test. That one assertion would have caught the bug before release.
Q: Is this an Android-only issue?
A: iOS has its own quirks with URL schemes. Apple recommends reverse-DNS schemes like com.example.app, which are longer but handled differently. We tested on iOS and saw no failures, but we still shortened the scheme to keep parity. The lesson is that platform-specific limits are easy to miss when you assume symmetry.
Why Small Details Decide App Reliability#
Q: How do you prioritize details like this in a release?
A: We now run a "string audit" before any rebrand or scheme change. It checks all user-facing and system-facing strings for length limits, reserved characters, and encoding issues. It is a simple script, but it forces us to think about the edges. The scheme length was not on our radar because it had never been a problem before.
Q: What advice do you have for other mobile teams?
A: Treat every identifier as a potential constraint. URL schemes, bundle IDs, API keys, and even file names have limits. Document them. Test them at the boundaries. And when you rebrand, do not assume that a cosmetic change is harmless. The smallest detail can break the most critical flow.
Q: What is the one thing you would change about how mobile platforms document these limits?
A: I would like to see a single page that lists all string length limits for intents, schemes, and permissions. Right now, the information is scattered across source code comments and old Stack Overflow posts. A clear reference would save teams days of debugging. Until then, we write our own checks and share them internally.
Q: How has this changed your release process?
A: We added a pre-release checklist item: "Verify all URL schemes and deep link patterns against platform limits." It is a five-minute check, but it has already caught two other potential issues, including a scheme that was too close to a reserved word. The process is lighter than a full audit, but it closes the gap that let this bug through.
Q: Any final thought on the smallest detail?
A: In mobile, the smallest details are often the ones users never see until they fail. A scheme length is invisible until a link does not work. The fix is cheap, but the discovery is expensive. Build guardrails for the details you cannot see, and you will spend less time chasing ghosts.
More articles