dns zone file · 14 min read
Why Your Zone File Won't Load: Diagnosing Common DNS Zone File Syntax Errors
Learn how to read a zone parser's error output, fix the mistakes that break zone loads most often, and build a validation step that catches DNS zone file syntax errors before they reach production.
Zone files fail often.
Zone file syntax errors halt domain resolution. Authoritative nameservers fail to load the zone, or they generate malformed records that fail resolver queries across the Internet. Identifying the exact parser failure before editing the file lets you restore resolution immediately without introducing secondary configuration bugs.
Two failure modes exist.
A hard failure forces the name server daemon to reject the zone file completely, causing recursive resolvers to receive SERVFAIL responses for every record under the origin. A soft failure allows the zone to load while an individual record contains syntactical errors that produce unintended hostnames, drop routing directives, or return unexpected data. Resolving both classes requires understanding the parsing rules defined in standard zone text representations specified by RFC 1035.
The fast fix: read the parser error before you touch the file
Check daemon logs first.
When an authoritative server rejects a zone file, the parser emits a specific log line pointing to the line number and the token where execution halted. In ISC BIND, named-checkzone provides the exact location of the failure:
$ named-checkzone example.com /etc/bind/zones/db.example.com
/etc/bind/zones/db.example.com:24: unexpected end of line
/etc/bind/zones/db.example.com:24: number of class/type/data tokens is incorrect
zone example.com/IN: loading from master file /etc/bind/zones/db.example.com failed: unexpected end of line
zone example.com/IN: not loaded due to errors
Triage zone loading failures in a systematic sequence:
- Identify the exact file path and origin name that failed to compile.
- Run an offline syntax linter against the local file instead of editing files directly on active nameservers.
- Read the first reported error and ignore subsequent errors until that initial issue is resolved.
- Repair the specific line and rerun the validator.
DNS parsers read text sequentially. A single missing quotation mark on line 12 or an unescaped semicolon in a TXT record breaks tokenization for the remainder of the file. That single mistake can produce dozens of downstream syntax errors on lines that are formatted correctly. Correcting the initial token error frequently resolves every downstream warning at once.
Strictness varies by implementation. BIND and NSD refuse to serve a zone file that contains any structural syntax error, continuing to serve the previous version from memory or returning SERVFAIL if no prior copy exists. Some DNS control planes and managed platforms sanitize imports by dropping invalid lines while loading the remaining records. Understanding how your nameserver processes failures prevents troubleshooting a missing record when the parser dropped it during ingest.
The eight DNS zone file syntax errors that break most zone loads
Syntax rules are strict.
While DNS zone files support dozens of record types, parser failures generally originate from eight specific syntax violations.
1. Missing trailing dot on a fully qualified domain name
Relative names append the origin.
The DNS text format treats any domain name that does not end in a period as relative to the current zone origin. If your zone origin is example.com. and you write a canonical name target as cdn.provider.com without a trailing period, the parser evaluates the target as cdn.provider.com.example.com., creating an unintended subdomain that resolvers cannot locate. The compiler accepts the relative name, but resolvers fail to find the synthesized record.
Consider this standard CNAME declaration:
; Incorrect: missing trailing dot appends zone origin
static.example.com. 300 IN CNAME target.externalcdn.net
; Correct: explicit dot terminates the domain name
static.example.com. 300 IN CNAME target.externalcdn.net.
This rule applies equally to NS, MX, PTR, and SRV target fields. For instance, declaring mail.example.com. 3600 IN MX 10 mailserver causes the server to point to mailserver.example.com. instead of an external mail exchanger. If an external host was intended, omitting the final period produces silent delivery failures.
2. Unbalanced parentheses in multi-line records
Multi-line records use parentheses.
Records like the Start of Authority (SOA), DKIM public keys, and SRV groupings use parentheses to span line breaks. If you omit the closing parenthesis or place a comment character before it, the parser treats all subsequent records as continuation data for the open record. This produces errors like unexpected end of file or reports that record types on subsequent lines are invalid tokens within the open field.
The parser reads everything between ( and ) as a continuous list of arguments across line breaks. A common error involves placing the closing parenthesis after a semicolon comment:
; Broken multi-line SOA: parenthesis placed inside comment
@ 3600 IN SOA ns1.example.com. hostmaster.example.com. (
2026103101 ; serial
7200 ; refresh
3600 ; retry
1209600 ; expire
300 ) ; minimum TTL
In the snippet above, the parser ignores ) because it follows the semicolon on the same line. The parser continues searching for a closing parenthesis, consuming subsequent records until it hits the end of the file. Place the closing parenthesis on its own line or before any comment markers to avoid tokenization traps.
3. TTL and class fields in the wrong order or using invalid values
Field order is rigid.
Standard representations place the owner name first, followed by optional time-to-live (TTL) and class values, the record type, and the record data (RDATA). Placing the class before the TTL (such as IN 3600 A instead of 3600 IN A) fails on strict parsers that expect the integer or valid duration unit in the second or third position. Supplying a non-numeric TTL without supported unit specifiers (such as 1h or 1d in BIND) generates an immediate syntax rejection.
According to RFC 2181 Section 8, a TTL is an unsigned integer in the range 0 to 2147483647 (2^31 - 1). Supplying a negative number or a value exceeding 2147483647 causes compilers to reject the record. Additionally, modern zone files should begin with a $TTL directive:
$TTL 86400
$ORIGIN example.com.
@ IN SOA ns1.example.com. admin.example.com. (
2026103101 7200 3600 1209600 300 )
If you omit $TTL and omit explicit TTL values on initial resource records, RFC-compliant parsers will raise an error stating that the default TTL is missing.
4. Missing, duplicated, or non-incrementing SOA records
Every zone requires one SOA.
It must appear at the beginning of the file before any other resource records for the zone. Duplicating the record causes the parser to reject the file immediately. When updating a zone file, failing to increment the 32-bit serial number prevents external nameservers or secondary systems from synchronizing changes, even if the file syntax is pristine.
The standard convention uses the date-based format YYYYMMDDnn, where nn represents a two-digit revision counter for that day. For example, the first edit on October 31, 2026 takes the serial 2026103101. The serial number field is a 32-bit unsigned integer governed by serial number arithmetic defined in RFC 1982. Jumping from a low number to a number greater than 2^31 - 1 wraps the arithmetic space, causing downstream parsers to classify the new serial as older than the existing one.
5. Unescaped or oversized TXT strings
String lengths have strict limits.
According to PowerDMARC's analysis of DNS TXT records, a single character-string within a TXT record cannot exceed 255 octets in length. When configuring long values such as 2048-bit DKIM keys or complex SPF policies, the string must be split into multiple quoted segments enclosed in parentheses. Failing to split a 300-byte string into contiguous chunks, or pasting unescaped double quotes inside the string, triggers string too long or tokenization errors during validation.
Here is how a 2048-bit DKIM key must be split within a zone file:
; Correct multi-string TXT record split below 255-octet boundary
k1._domainkey.example.com. 3600 IN TXT (
"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Y3wQ"
"l1u7G8d1P9e5K4L2m8F0J4a9B3v1C6x8Z5q2W9y3T7u1I5o8P3m4N6b7V8c9X0z1A2"
"B3c4D5e6F7g8H9i0J1k2L3m4N5o6P7q8R9s0T1u2V3w4X5y6Z7a8B9c0D1e2F3g4H5"
"IDAQAB" )
DNS resolvers automatically concatenate these sequential strings into a single value without adding delimiters. If you do not enclose the multi-line strings in parentheses, the parser will treat the second line as a brand new resource record, raising an error about an invalid record type on the orphaned string.
6. Invalid characters in owner names and incorrect wildcards
Hostname labels face character constraints.
Standard hostnames must conform to RFC 952 and RFC 1123, which restrict characters to letters, digits, and hyphens. While DNS labels technically accept any octet, host-resolving record types like A, AAAA, and CNAME will fail validation under strict checking flags if labels contain underscores or spaces. Wildcard asterisks (*) must appear only as the leftmost label in a name, such as *.example.com..
Declaring sub.*.example.com. or app*.example.com. is invalid under RFC 4592 Section 2.1.1. Parsers reject these pseudo-wildcards immediately. Underscores are permitted only in specific record types designed for service discovery and metadata verification, such as _dmarc.example.com., _tcp.example.com., or _sip._tcp.example.com. for SRV records. Putting an underscore in an A record label like web_server.example.com. causes check utilities like named-checkzone -k fail to reject the zone file outright.
7. CNAME co-existence violations
A CNAME cannot share an owner name with other data.
According to RFC 1034 Section 3.6.2, if a CNAME record is present at a node, no other data may exist for that node. A common syntax violation occurs when an engineer specifies both an A record and a CNAME record for the same hostname:
; Invalid CNAME co-existence
app.example.com. 300 IN A 192.0.2.10
app.example.com. 300 IN CNAME app-cdn.vendor.net.
The parser rejects this configuration because canonical names represent an absolute alias. When a resolver receives a CNAME, it restarts the lookup using the canonical target name. If other records existed at that label, the resolver would face contradictory routing instructions.
This restriction creates a critical hurdle at the zone apex (example.com.). The zone apex must always hold SOA and NS records. Because of the CNAME co-existence rule, you cannot place a standard CNAME record at @ or example.com. without breaking RFC compliance. While standard zone files forbid CNAMEs at the apex, managed solutions handle this via record flattening. For example, DNSCove supports apex ALIAS records (CNAME-at-apex flattening, like Route53 Alias) with serve-stale protection.
8. Missing glue records and malformed delegations
Delegations require reachable name server targets.
When you delegate a subdomain to child nameservers whose names fall inside that child domain, you must provide glue records in the parent zone. Failing to supply glue records leaves recursive resolvers with an unresolvable cyclic dependency:
; Subdomain delegation requiring glue
sub.example.com. 3600 IN NS ns1.sub.example.com.
sub.example.com. 3600 IN NS ns2.sub.example.com.
; Glue records providing address data for child nameservers
ns1.sub.example.com. 3600 IN A 198.51.100.5
ns2.sub.example.com. 3600 IN A 198.51.100.6
If you declare the NS records for sub.example.com. pointing to ns1.sub.example.com. but omit the corresponding A or AAAA records in this parent file, strict linters flag the file for missing glue. Resolvers attempting to query sub.example.com. will query the root, query the TLD, query the parent nameserver, and then receive a referral pointing to an address they cannot resolve.
Tooling and commands to validate zone files before deployment
Validate locally before pushing to nameservers.
Deploying an unvalidated zone file directly into a production directory risks an outage. Running command-line linters in your continuous integration pipeline catches syntax blunders before they reach authoritative daemons.
Three primary open-source verification utilities cover the major parser implementations:
- ISC BIND
named-checkzone: The standard against which most RFC parsing rules are measured. - NLnet Labs
nsd-checkzone: A strict validator tailored for NSD authoritative servers. - CZ.NIC
kzonecheck: The Knot DNS verification utility, known for rapid lexical analysis and semantic checking.
Here is how to run named-checkzone with strict semantic checks:
$ named-checkzone -k fail -m fail -M fail -S fail example.com /path/to/db.example.com
zone example.com/IN: loaded serial 2026103101
OK
The flags ensure deep scrutiny:
-k fail: Rejects hostnames containing characters that violate RFC 952 and RFC 1123, such as underscores in address records.-m fail: Checks MX record targets to ensure they point to hostnames rather than raw IP addresses.-M fail: Verifies that MX records do not point to CNAME aliases.-S fail: Rejects SRV targets that resolve to CNAMEs.
For NSD environments, use nsd-checkzone:
$ nsd-checkzone example.com /etc/nsd/example.com.zone
zone example.com is ok
If an error exists, nsd-checkzone returns a non-zero exit code and outputs the file line and failing token. Knot DNS provides kzonecheck, which provides clean semantic analysis:
$ kzonecheck -z example.com /path/to/db.example.com
Zone is syntactically and semantically correct.
Integrating one of these commands into a pre-commit hook or deployment pipeline prevents malformed zone files from entering production nameservers.
Differences in how DNS parsers handle syntax errors
Daemons interpret edge cases differently.
Although RFC 1035 defines the text zone format, parsers in production software handle ambiguous grammar, unescaped characters, and semantic anomalies with differing severity levels.
BIND operates with strict structural adherence. If a zone file contains an unescaped character or a duplicated SOA record, BIND refrains from serving the updated zone entirely. If the zone was loaded previously, BIND maintains the in-memory version and logs a critical error. If the server is restarting from cold storage, BIND answers queries for that domain with SERVFAIL.
NSD requires the zone file to be compiled into a binary database format (nsd.db) via nsd-control reload or zone compilation daemons. If the text zone contains a syntax error, the compiler rejects the transaction. The database retains the prior state, ensuring that invalid syntax does not overwrite healthy zone memory.
Knot DNS emphasizes speed and strict semantic enforcement. By default, Knot inspects relationships between records, rejecting configurations where an MX or NS points directly to a CNAME. BIND permits these delegations by default unless configured with strict warning flags.
Managed DNS platforms and cloud providers often implement web-based zone import tools. These interfaces parse standard zone text files, but their ingest pipelines frequently differ from traditional UNIX daemons. Some interfaces discard malformed records silently and import valid lines, creating gaps in your zone mapping. Others reject the entire upload and supply generic error messages that lack line numbers. Migrating zone files across providers requires validating files locally first so that parser differences do not obscure configuration problems.
Frequently asked questions
What does "unexpected end of file" mean during named-checkzone?
This error indicates that the parser reached the end of the zone file while waiting for a closing symbol. The most common cause is an unclosed parenthesis in a multi-line record like an SOA, DKIM key, or SRV group. It can also occur if an unclosed double quotation mark was left on a TXT record, causing the parser to treat every subsequent line as literal string text.
Can I use an underscore in an A or AAAA record?
No. RFC 1123 restricts hostnames for address records to ASCII letters, digits, and hyphens. While DNS labels can technically store arbitrary binary octets, standard resolvers and DNS validators reject address records that contain underscores. Underscores are reserved for service identification records such as SRV, TLSA, and TXT verification records like DKIM and DMARC.
Why is my new DNS record returning NXDOMAIN after editing the zone file?
Two reasons typically cause this. First, the nameserver daemon might have encountered a syntax error elsewhere in the zone file, causing it to reject the reload and keep serving the previous version. Second, if you added the record to the primary server, you may have forgotten to increment the SOA serial number. Without a higher serial number, secondary servers will not pull the updated records.
Can a CNAME record point to an IP address?
No. The RDATA field of a CNAME record must contain a valid domain name, terminated with a trailing dot if fully qualified. Placing an IPv4 or IPv6 address in the target field of a CNAME violates RFC 1034 and causes the parser to reject the record. If you need to map a name directly to an IP address, use an A record for IPv4 or an AAAA record for IPv6.
How do I write a TXT record longer than 255 characters?
Split the text into multiple quoted strings enclosed in parentheses. The DNS protocol restricts individual character strings to 255 octets, but a single TXT resource record can hold multiple strings totaling thousands of octets. Resolvers concatenate these strings automatically during retrieval. For example: example.com. IN TXT ( "first part " "second part" ).
What happens if I forget the trailing dot on an MX target?
If you omit the trailing dot on an MX target, the nameserver appends the zone origin to the target hostname. For example, if your zone is example.com. and you write mail.google.com without a trailing dot, the record resolves to mail.google.com.example.com.. Mail servers attempting to deliver messages will fail to find that target and bounce incoming email.
- No AWS account required
- Zero-downtime Route 53 cutover
- Apex ALIAS / ANAME to any target
- DNS as code — Terraform, CloudFormation
Straight answer: DNSSEC signing isn't available yet — it's on the roadmap. Everything else here works today. Authoritative nameservers: ns1.dnscove.com, ns2.dnscove.org.