You mount an existing sub-application under a path prefix and its generated links now point to the wrong place — how do you diagnose and fix that?

Mounting is registration at the level of a whole routing tree: instead of adding one entry, you attach another application's entire table under a base path. It is how a service composes an admin area, a versioned surface, or a library-provided set of endpoints, and it is where prefix bugs concentrate, because a sub-application written for the root of a host suddenly is not at the root any more. ## The two contracts that must agree Mounting at `/admin` splits into two independent questions, and most mount bugs are one of them answered wrongly: 1. **Inbound: which path does the inner tree match against?** Frameworks differ — many strip the mount base and hand the remainder down, so inner routes are declared as if they were at the root; others pass the full path, so inner routes must include the prefix. Getting this backwards produces a uniform `404` for everything inside the mount, which is at least loud. 2. **Outbound: which base does the inner tree build links from?** Nothing in an incoming request reliably carries "you were mounted at `/admin`"; it is configuration passed at mount time. Get this wrong and every route still resolves, but every link, redirect and cookie is subtly off — quiet, and usually found by a user. ## Everything that carries the base The symptom is described as "links", but the base leaks into more places than anchors in rendered output: - **Redirect targets.** A `Location` header built from the inner root sends the client outside the mount, often to a `404` or, worse, to a different application that happens to own that path. - **Cookie scope.** A cookie written with `Path=/` from inside a mount is broader than intended; one written with the inner path is narrower than the mount and will not be sent back for sibling routes. - **Static or asset references** emitted by the sub-application, which were correct at the root. - **Form targets and callback URLs** the sub-application hands to a client and expects to receive back. - **Absolute links**, which add scheme and host to the same wrong base and are the hardest to spot in review. ## How to diagnose, in order 1. **Print the effective route inventory.** If the entries do not show the prefix, the mount did not happen the way you think and the problem is registration, not link building. 2. **Log the path the inner handler receives.** That tells you which inbound convention your framework uses, and it distinguishes "nothing matches" from "everything matches but links are wrong". 3. **Look at a generated link next to a hand-built one.** If generated links are right and hand-built ones are wrong, the fix is mechanical: move the call sites onto the generator. 4. **Check redirects and cookies specifically**, because they fail later and quieter than an anchor a tester can see. | Symptom | Likely cause | |---|---| | Every inner route returns 404 | Inbound convention mismatch: base stripped when the routes expect it, or vice versa | | Pages render but links drop the prefix | Sub-application generating from its own root; mount base not configured | | Login redirect leaves the mounted area | `Location` built by concatenation rather than through the generator | | Session lost when moving between inner pages | Cookie `Path` scoped to a single inner path instead of the mount base | | Two mounts fight over one prefix | Overlapping bases registered; detectability depends on the framework | ## Fixing it properly The durable fix is to make the mount base a **first-class value the sub-application is told once**, and to generate every outbound path through the router so the base is applied automatically. Concretely: pass the base at mount time rather than hardcoding it inside; build links and redirect targets by route name; derive cookie `Path` from the same base; and forbid string concatenation of the prefix in call sites, because a single missed site reproduces the bug. Two further habits keep mounts healthy. **Reserve prefixes explicitly** so two mounts cannot claim overlapping bases by accident, and check whether your framework rejects that at startup — do not assume it always does. And **test one link, one redirect and one cookie from inside the mount**, since those three exercise all the places the base travels. A mounted application that is correct at the root and correct under a prefix is a sub-application you can move again later without fear, which is the whole point of mounting rather than copying routes.