Common BIND Zone File Errors

How to identify and fix the most frequent zone file mistakes

When named-checkzone reports an error in your zone file, the messages can be cryptic. This guide covers the most common errors, explains what causes them, and shows you how to fix them.

1. Missing Trailing Dot on FQDNs

This is by far the most common mistake. In BIND zone files, any domain name that doesn't end with a dot is treated as relative to the zone origin. BIND automatically appends the zone name to it.

The Problem

; Zone: example.com
www   IN  CNAME  example.com     ; WRONG!
; BIND interprets this as: www.example.com. CNAME example.com.example.com.

The Fix

www   IN  CNAME  example.com.    ; Correct -- trailing dot makes it absolute

This applies everywhere a fully qualified domain name appears: NS record targets, MX record targets, CNAME targets, SOA fields, and SRV record targets. If you mean a fully qualified name, always add the trailing dot. Note that named-checkzone may still parse the zone successfully in some cases, but the resulting name will often be wrong and can trigger follow-on errors such as missing address records.

2. CNAME Conflicts

A CNAME record cannot coexist with any other record type at the same name. This is defined in RFC 1034 and strictly enforced by BIND.

The Problem

www   IN  A      93.184.216.34
www   IN  CNAME  example.com.    ; ERROR: conflicts with the A record above

The Fix

Choose one approach -- either use an A record or a CNAME, not both:

; Option A: Use just the A record
www   IN  A  93.184.216.34

; Option B: Use just the CNAME
www   IN  CNAME  example.com.

Similarly, you cannot place a CNAME at the zone apex (@) because the apex must have SOA and NS records.

3. Missing or Invalid SOA Record

Every zone file must have exactly one SOA record, and it must be the first record in the zone (after any directives like $TTL).

Common SOA Problems

• Missing SOA entirely -- the zone won't load at all
• Wrong field count -- the SOA has 7 required fields inside the parentheses
• Admin mailbox written in an unusual form -- the conventional DNS representation of [email protected] is admin.example.com., though special characters in the local part may need escaping
• Missing parentheses -- multi-line SOA records require parentheses

Correct SOA Format

@   IN  SOA  ns1.example.com. admin.example.com. (
                2024010101   ; Serial
                7200         ; Refresh
                3600         ; Retry
                1209600      ; Expire
                3600         ; Minimum TTL
)

4. SOA Serial Number Not Incremented

While named-checkzone won't always flag this as an error, failing to increment the serial number is a common operational mistake. Secondary nameservers check the serial to decide whether to transfer a new copy of the zone. If you don't increment it, your changes won't propagate.

Best Practice

Use the YYYYMMDDnn format:

; Today's first change
2024061401

; Today's second change
2024061402

; Tomorrow's first change
2024061501

The serial number must always increase. If you use Unix timestamps or arbitrary numbers, just make sure each new value is larger than the previous one.

5. Missing NS Records

Every zone must have at least one NS record at the zone apex. In practice, you should have at least two for redundancy. Without NS records, the zone is technically invalid.

The Fix

@   IN  NS   ns1.example.com.
@   IN  NS   ns2.example.com.

6. TTL Issues

If no $TTL directive is present and records don't specify their own TTL, BIND may reject the zone or use unexpected defaults.

The Problem

; No $TTL directive, no per-record TTL
@   IN  A  93.184.216.34          ; What TTL does this get?

The Fix

Always include a $TTL directive at the top of your zone file:

$TTL 3600    ; 1 hour default TTL

@   IN  A  93.184.216.34          ; Gets 3600s TTL from $TTL directive

You can override the default for individual records by specifying a TTL value:

$TTL 3600
@       IN  A  93.184.216.34      ; 3600s (default)
www  60 IN  A  93.184.216.34      ; 60s (overridden)

7. Syntax Errors in Record Values

Each record type has a specific format. Common mistakes include:

MX Records Missing Priority

; Wrong -- missing priority number
@   IN  MX  mail.example.com.

; Correct
@   IN  MX  10  mail.example.com.

TXT Records Written Without Quotes

; Risky -- BIND treats this as multiple TXT character-strings
@   IN  TXT  v=spf1 mx -all

; Clear and predictable
@   IN  TXT  "v=spf1 mx -all"

This is not always a syntax error, but it's easy to get unintended TXT content if you omit quotes around values with spaces. For SPF, DKIM, and verification tokens, use quoted strings unless you deliberately want multiple TXT strings.

A Records with Invalid IPs

; Wrong -- not a valid IPv4 address
www  IN  A  999.999.999.999

; Wrong -- IPv6 in an A record (use AAAA)
www  IN  A  2606:2800::1

8. Tab and Whitespace Issues

BIND zone files use whitespace (spaces or tabs) as field separators. Inconsistent whitespace usually isn't a problem, but there are edge cases:

• Lines that start with whitespace inherit the previous record's owner name, which can be surprising if you intended a new name
• Empty lines between records are fine, but an empty line inside a parenthesised block may cause issues with some BIND versions

9. Duplicate Records

While not always an error, duplicate identical records are wasteful and can indicate a mistake. Duplicate records with different values at the same name are valid for some types (A, MX, NS, TXT) but invalid for CNAME and SOA.

; Valid: multiple A records (round-robin DNS)
www  IN  A  93.184.216.34
www  IN  A  93.184.216.35

; Invalid: multiple CNAMEs for the same name
www  IN  CNAME  server1.example.com.
www  IN  CNAME  server2.example.com.   ; ERROR

10. Out-of-Zone Data

Records in a zone file should belong to the zone. If you're editing the zone for example.com, records for otherdomain.com are out of place and usually indicate a mistake.

; Zone: example.com
; This record is out of zone -- named-checkzone will usually ignore it
otherdomain.com.  IN  A  1.2.3.4

In practice, named-checkzone often loads the zone and logs a warning such as ignoring out-of-zone data. That still means the record is being discarded, so you should fix it rather than rely on the zone loading.

Quick Reference: Error Messages