How to Recognize a Context Mismatch Quickly
When a bug report says, “the text looks encoded and the link still fails,” the output itself usually tells you which layer was handled incorrectly. You do not need a dramatic debugging ritual. Start with the visible shape of the string.
- If you see lots of percent sequences such as
%20or%3Cin normal page text, URL encoding was probably applied where HTML rendering was expected. - If you see entity text such as
&or<on the page, HTML entity encoding may have been applied twice or too early. - If a link breaks around ampersands or question marks, a query string or URL component may not have been percent-encoded correctly before it was assembled.
- If an attribute seems to “spill” into the surrounding markup, the value likely was not encoded for the attribute context, or the attribute was not quoted properly.
This kind of diagnosis is useful because it keeps the fix small. Instead of asking, “Which sanitizer should we add?” ask, “Which parser reads this string next?” That question usually leads you to the right layer much faster.
It also explains why logs and screenshots can be misleading. A value may look clean in a raw log line and fail in a browser-based report, or look strange in source while rendering correctly on the page. The visual result matters, but so does the parser that produced it. Read the output in context, not in isolation.
Reasonable Defaults by Scenario
- Query string or path component: use URL encoding for the component you are adding.
- Visible page text: use HTML entity encoding before rendering.
- HTML attribute: use HTML entity encoding for the attribute context, with quotes in place.
- Reports and browser-visible logs: treat them as output destinations and encode for the rendering layer, not as a universal cleanup step.
Final Takeaway
The best fit depends on destination. If the string is traveling inside a URL, percent-encode the relevant URL component. If the string is being rendered inside HTML, entity-encode for that output context. Most failures come from choosing one transformation and trying to use it everywhere.
Pick the scenario that matches your next task, apply the safest reasonable default, and verify the result where it will actually live. If you want supporting references, browse Sources/Functions…. If you want broader site resources, start from the home page. If you are still unsure which layer you are working in, use Support before the next round of encoding turns a small bug into a long afternoon.