Rentgen

Uppercase Domain Handling — when your API breaks because someone typed “LOCALHOST”

Rentgen API Stories · January 2026

This is one of those bugs that looks too stupid to exist — until you see it in production. Someone types a domain in uppercase (API.EXAMPLE.COM or LOCALHOST), and the backend responds with 500, 404, or some other nonsense.

The scary part? It’s rare, so it’s almost never tested. And when it happens, it’s usually discovered the worst way possible: by a frustrated developer, in a rushed integration, at midnight.

What was tested

Rentgen takes your original request and changes only one thing: the domain casing. It turns the host into uppercase and expects the API to behave normally.

  • TEST: Uppercase Domain Test
  • Mutation: Host/domain converted to uppercase
  • Expected: Any 2xx success (same behavior as normal request)
  • Example result: 🟢 Pass (200 OK)
  • If not 2xx: Rentgen marks it as a real bug — because the server is reacting to casing, not logic
Uppercase Domain Test in Rentgen
Rentgen mutates the host casing and checks whether the API stays stable

Why this matters (even if it’s “rare”)

Domain names are effectively case-insensitive in real-world usage, and many layers treat them that way: DNS lookups, client libraries, proxies, browsers, and common tooling. If your API breaks when the host casing changes, it means somewhere in your stack you’re treating the host as case-sensitive text — which is a configuration smell.

This bug is expensive in the most annoying way: it wastes time. Not because it’s hard to fix — but because nobody expects it. People debug the payload, the auth, the query params, the headers… when the “root cause” is literally a capitalization difference.

What Rentgen found

In your run:

  • Expected: 2xx
  • Actual: 200 OK
  • Status: 🟢 Pass

Good. This is how it should be: the API doesn’t care if the domain is typed as api.example.com or API.EXAMPLE.COM.

Where this fails in real systems

When it fails, it usually fails because of infrastructure assumptions — not application logic. Typical culprits:

  • Reverse proxy / gateway routing rules that match Host as a case-sensitive string
  • Virtual host config that doesn’t normalize the incoming host
  • Custom middleware that uses the host string directly (as a key, map lookup, or routing switch)
  • Local development stacks where “localhost handling” is inconsistent across tools

Why localhost is a special trap

You asked the right question: should this work for LOCALHOST? Yes. It should.

And ironically, localhost environments are where you’ll see this bug more often. Not because localhost is special — but because dev setups are full of hand-written configs: custom hosts files, local proxies, Docker networks, wildcard routing, and quick fixes that never get hardened.

If you build internal tools that run only locally or in a private network, this test is not “nice-to-have”. It’s a silent stability check. Local bugs have a habit of becoming production bugs later — just with better excuses.

What’s the worst that can happen?

Nothing “hacker movie” style. Just real-world pain:

  • Random 404s depending on how a client formats the URL
  • 500 spikes in local environments that nobody can reproduce consistently
  • Support tickets where the user swears “the endpoint is down” (and they’re not wrong)
  • Broken integrations where one library normalizes host casing and another doesn’t

How to fix it (pragmatic checklist)

Fixing this is usually not a code rewrite. It’s configuration discipline:

  • Normalize the incoming host (lowercase) at the edge (proxy/gateway) before routing decisions
  • Ensure your routing rules don’t depend on case-sensitive host matching
  • For local stacks, verify your dev proxy behaves the same way as production
  • If you use host-based multi-tenancy, treat host values as identifiers that must be normalized

Why I put this into Rentgen

Because testers rarely check this manually. Not because they’re lazy — because it feels pointless… until it’s not.

Rentgen does it automatically: the test costs almost nothing to run, and when it fails, it saves hours of debugging that would otherwise end with: “Wait… you typed it in uppercase?”

Final thoughts

If it passes: perfect — move on. If it fails: treat it as an infrastructure bug, not a “weird client issue”. Your API shouldn’t behave differently because someone used Caps Lock.