Choosing a business name with a dot in it can lead to unexpected and frustrating technical issues, particularly with server hostnames and DNS resolution. Learn how to diagnose and fix these problems before they cause a production outage.

So, You Put a Dot in Your Hostname. Let’s Talk.

I remember it like it was yesterday. 3 AM, the on-call pager screaming, and our entire checkout service was down. The error? “Cannot resolve hostname: prod-api.v1.checkout”. We spent a solid hour tearing our hair out, checking network ACLs, DNS records, everything. The weird part? prod-api-v1-checkout worked just fine. Turns out, a junior engineer, trying to be clever with versioning, named a server with a dot. A legacy Java service we relied on saw that dot and immediately tried to resolve “v1.checkout” as a domain, which, of course, didn’t exist. That simple dot cost us thousands in lost revenue and my entire night’s sleep. Naming things is one of the hardest problems in computer science, and this is exhibit A.

The “Why”: Dots Are Not Your Friends in Hostnames

Look, I get it. You’re trying to organize things. Maybe your company is “Next.Gen AI” and you want to name a server web.next.gen.ai-prod-01. It seems logical. But in the world of DNS and networking, the dot is a sacred character. It’s a delimiter. It separates the parts of a Fully Qualified Domain Name (FQDN).

The root of the problem is ambiguity. When a system sees a name like prod-db.01.us-east-1.mycorp.com, how does it know where the hostname ends and the domain begins? Is the hostname prod-db.01 or just prod-db? While many modern DNS resolvers are smart about this (thanks to settings like ndots), a shocking number of applications, libraries, and older scripts are not. They’ll make a bad guess, fail to resolve the name, and your application falls over.

Darian’s Rule of Thumb: The only dot in a server’s FQDN should be the ones separating it from its domain and subdomains. The hostname itself? Stick to letters, numbers, and hyphens. Period.

The Fixes: From Duct Tape to a New Engine

So you’re in this mess. An important service can’t talk to a server because of a dot in its name. You’ve got options, ranging from “get me out of this outage now” to “let’s fix this properly so it never happens again.”

1. The Quick Fix: The `/etc/hosts` Hammer

This is the duct tape solution. It’s ugly, it doesn’t scale, and it will almost certainly cause you pain later. But if production is on fire and you need to get a specific client machine talking to a specific server right now, you can manually override DNS on the client machine.

You SSH into the client machine (the one that can’t resolve the name) and edit the /etc/hosts file to add a manual entry.

# /etc/hosts on client-app-01

# Previous entries...
127.0.0.1   localhost

# HACK: Manually resolve the badly named server
10.10.1.23  prod-db.01.us-east-1.mycorp.com prod-db.01

Why it’s a hack: This only fixes the problem for one client. If you have 50 app servers, you have to do this 50 times. And what happens when the IP of prod-db.01 changes? You have to go update all 50 files again. Use this to stop the bleeding, then immediately start planning a real fix.

2. The Permanent Fix: Rename and Standardize

This is the right way to do it. It’s the solution you’d present in a post-mortem. You fix the source of the problem: the bad hostname. You establish a clear, unambiguous naming convention for all future infrastructure.

The plan is simple:

1. Establish a new naming convention. Use hyphens instead of dots.
2. Plan a maintenance window. You’ll need to briefly take the server offline.
3. Rename the host on the machine itself.
4. Update the corresponding DNS record (your A or CNAME record) to point to the new name.
5. Update any configuration management (Ansible, Puppet, Terraform) or application configs that explicitly reference the old name.

Here’s what that looks like in practice:

This completely removes the ambiguity. No system on earth will misinterpret app-v2-worker.

3. The ‘Nuclear’ Option: Messing with Resolver Configs

Sometimes, you can’t rename the host. It’s a black box appliance, a legacy system nobody dares touch, or some other political nightmare. In these desperate cases, you can sometimes fix the *client* by changing how it resolves names.

On most Linux systems, the file /etc/resolv.conf controls DNS behavior. The ndots option is key here. It tells the system how many dots must be in a name before it tries to resolve it as an absolute FQDN. By default, this is often 1. If a name has fewer dots, the resolver will try appending the domains in your search path.

Let’s say your search path is eu-west-1.mycorp.com mycorp.com. When you try to resolve app.v2.worker (which has 2 dots), the system might try it as an absolute name first, fail, and then give up.

You can force its behavior by increasing ndots:

# /etc/resolv.conf

# Tell the resolver to append search domains for any name with < 5 dots
options ndots:5

search eu-west-1.mycorp.com mycorp.com
nameserver 1.1.1.1

Warning: Be extremely careful with this. Changing resolver behavior can have wide-ranging, unintended consequences. It can slow down DNS lookups and mask the real problem. This is a last resort when The Permanent Fix is truly impossible. You’re treating the symptom, not the disease.

At the end of the day, keep it simple. Your server names aren’t the place for creative punctuation. A hyphen is your best friend. It will save you from a 3 AM pager alert, and that’s something we can all agree is a good thing.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions