Follow a request to its template
Start with the URL that gives an unexpected result. Check its hostname: Zotonic uses it to select a site before matching the site's dispatch rules.
Run bin/zotonic dispatch garden /welcome. Read the selected dispatch name, controller, and arguments. A template controller renders its configured template. A page controller also works with a content resource, often available as id in the template.
Next, inspect the active template selected for that name. Includes and category variants can select additional files from other active modules. Use Find the template used by a page to find those files. Test the actual browser request too: dispatch inspection does not reproduce every authentication, language, or response condition.
Link to resources and dispatch routes
Use a resource's page URL when linking to content. This lets Zotonic account for its path and language.
<a href="{{ m.rsc.page_home.page_url }}">{_ Home _}</a>
For an application endpoint, use a named dispatch route:
<a href="{% url admin %}">{_ Admin _}</a>
Do not add separate normal content routes for each language. Configure the resource and language support instead. Avoid building internal URLs by joining strings: escaping, optional arguments, and language prefixes belong to the dispatcher.
Trace URL dispatch from the command line
Use dispatch inspection to discover why a path selects a particular controller:
bin/zotonic dispatch garden
bin/zotonic dispatch garden detail
bin/zotonic dispatch garden /welcome
The first form lists site rules, the second includes detail, and the third traces a path. You can also pass a full URL to include hostname-based site selection.
Compare the selected rule, controller, options, and any path rewriting with your expectation. Earlier applicable rules can win over a broad catch-all later in the list.
This is a dispatch diagnosis, not a substitute for making the HTTP request and checking authorization and rendering. See Trace a URL through dispatch and A URL reaches the wrong page.
A URL reaches the wrong page
Confirm the hostname, site, and path from the actual request. Use the dispatch trace to see the selected rule and any rewritten path.
Check route order and arguments, then inspect resource page paths and language handling if the URL is content-driven. A path tested against the wrong site can produce a convincing but irrelevant trace.
After changing a rule or resource path, refresh the relevant information and test the browser request, including its redirects. Verify another nearby URL to catch an overly broad match.