Field Guide

Debug Linux hostname resolution when `systemd-resolved` and search domains disagree with expectation.

Use this guide when hostnames resolve differently than expected across shell tools, applications, or network locations. The focus is on the local stub listener, route-only domain logic, single-label behavior, and `/etc/hosts` interaction.

Search Resolver IssuesOpen Linux Domain
Situation

`/etc/resolv.conf` alone does not explain modern Linux resolution.

On systems using `systemd-resolved`, the local stub listener, search domains, route-only domains, and NSS integration determine which names are queried where. That means the same host can appear healthy from one tool but broken from another if the lookup path differs.

What To Verify

Confirm the resolver path, not just the server IP.

  • Check whether `/etc/resolv.conf` points at the stub listener or another file path.
  • Use `resolvectl status` to inspect per-link DNS servers and routing domains.
  • Determine whether the failing name is single-label, multi-label, or `.local` scoped.
  • Review `/etc/hosts` entries and whether they mask intended DNS behavior.
  • Confirm whether the application uses glibc/NSS resolution or bypasses it.
Working Sequence

Rebuild your understanding from the host outward.

  • Test the exact name format that fails, including short name versus FQDN.
  • Inspect link-specific DNS settings and search domains before changing global config.
  • Validate how the host handles single-label names in the current environment.
  • Temporarily reduce variables by testing with explicit FQDNs and known-good servers.
  • Document the intended route-only or search-domain design before making persistent changes.