Validate BIND Config with named-checkconf and named-checkzone (2026)

BIND configuration errors can be frustratingly subtle, often leading to unexpected DNS resolution failures or outright service outages. The primary tools for diagnosing these issues are named-checkconf and named-checkzone.

named-checkconf is your first line of defense, responsible for validating the syntax and general correctness of your BIND configuration files, most importantly named.conf and any files it includes. If named-checkconf reports an error, BIND won’t even attempt to load the configuration, preventing a startup failure.

Here’s how to use it and what to look for:

1. Basic Syntax Check:

The simplest way to check your main configuration file is:

named-checkconf /etc/bind/named.conf

If this command returns nothing, your named.conf and any included files have passed the initial syntax and structural checks. If it outputs errors, they will be specific, pointing to line numbers and the nature of the problem.

Common Causes and Fixes for named-checkconf Errors:

Syntax Errors (e.g., missing semicolon, misspelled keyword):
- Diagnosis: named-checkconf will explicitly state the error and line number. For instance: Error: missing ';' before '}' token at /etc/bind/named.conf:25
- Fix: Go to the specified line and add the missing semicolon or correct the misspelled keyword.
- Why it works: BIND, like many configuration-driven services, relies on precise syntax. A missing semicolon or a typo can break the parser’s ability to understand the configuration directives.
Incorrect File Paths for Included Files:
- Diagnosis: named-checkconf might report file not found errors for included files. Example: Error: unable to open file /etc/bind/zones/db.example.com: file not found
- Fix: Ensure the include directive in named.conf points to the correct, existing file path. If the file is meant to be in a different location, update the path:
```
# In named.conf
include "/etc/bind/zones/db.example.com";
```
  becomes
```
# In named.conf
include "/var/lib/bind/db.example.com";
```
- Why it works: BIND needs to read all its configuration directives. If an include statement references a non-existent file, BIND cannot parse the directives within that missing file, leading to an incomplete configuration.
Incorrect Permissions on Configuration Files:
- Diagnosis: BIND might fail to read its configuration files if the user it runs as (often bind or named) doesn’t have read permissions. named-checkconf might not always catch this directly, but BIND’s startup logs will show permission denied errors.
- Fix: Ensure the BIND user can read all configuration files and included directories.
```
chown -R bind:bind /etc/bind
chmod -R ug+r /etc/bind
```
- Why it works: The BIND process needs to access its configuration to know how to operate. Restricting read access prevents it from loading the necessary directives.
Invalid options Block Directives:
- Diagnosis: Errors related to specific options, like an invalid listen-on port or an unknown acl name. Example: Error: unknown ACL name 'internal-nets' at /etc/bind/named.conf:10
- Fix: Correct the directive. If it’s an ACL, ensure the ACL is defined earlier in the configuration:
```
# In named.conf
acl "internal-nets" { 192.168.1.0/24; 10.0.0.0/8; };
// ... later in the config ...
allow-query { internal-nets; };
```
- Why it works: BIND has a defined set of configuration options. Incorrectly formatted or undefined options prevent BIND from understanding its operational parameters.
Missing directory Directive:
- Diagnosis: If zone files are not in the default /var/cache/bind or /var/lib/bind directory and the directory option isn’t set in named.conf or a view, BIND won’t find them. named-checkconf might not flag this directly, but named-checkzone will complain about missing zone files.
- Fix: Add a directory directive to your options block or a relevant view:
```
# In named.conf options block
options {
    directory "/var/lib/bind/zones";
    // ... other options
};
```
- Why it works: The directory option tells BIND the base path where it should look for zone files referenced without a full path.
Incorrect listen-on or listen-on-v6 Syntax:
- Diagnosis: Errors related to IP addresses or network interfaces BIND should listen on. Example: Error: invalid listen address '192.168.1.256' at /etc/bind/named.conf:15
- Fix: Ensure the IP addresses are valid and within the configured interfaces. For example, to listen on a specific internal IP and all IPv6 addresses:
```
# In named.conf options block
options {
    listen-on { 192.168.1.10; };
    listen-on-v6 { any; };
    // ...
};
```
- Why it works: BIND needs to know which network interfaces and IP addresses to bind to for serving DNS queries. Invalid addresses prevent it from establishing these network sockets.

After named-checkconf passes without output, you can then move to named-checkzone to validate individual zone files.

named-checkzone example.com /etc/bind/zones/db.example.com

This command checks the syntax within a specific zone file and verifies that it is consistent with its SOA (Start of Authority) record and serial number.

Common Causes and Fixes for named-checkzone Errors:

Invalid Zone File Syntax (e.g., missing NS record, malformed record):
- Diagnosis: named-checkzone will report errors like missing NS record for zone example.com or Bad zone file format.
- Fix: Correct the syntax within the zone file according to DNS record standards. Ensure you have at least an NS record and A/AAAA records for the nameservers.
- Why it works: DNS zone files follow a specific RFC standard for defining records. Deviations break the parser’s ability to interpret the authoritative data for the zone.
Incorrect Zone Serial Number:
- Diagnosis: If you load a zone file with a serial number lower than the one currently loaded in BIND’s running configuration, BIND will ignore the update. named-checkzone might not explicitly flag this as an error, but BIND’s logs will show it being ignored.
- Fix: Always increment the serial number in the SOA record when making changes to a zone file. Use a YYYYMMDDnn format for easy tracking.
```
; SOA Record Example
@   IN  SOA ns1.example.com. admin.example.com. (
            2023102701  ; Serial
            3600        ; Refresh
            1800        ; Retry
            604800      ; Expire
            86400 )     ; Minimum TTL
```
- Why it works: The serial number is BIND’s primary mechanism for detecting zone file changes. A higher serial number signals to secondary DNS servers (and BIND itself, when reloading) that the zone data has been updated.
Mismatched Zone Name and Filename:
- Diagnosis: named-checkzone might report that the zone name in the named.conf zone statement doesn’t match the zone name implied by the file.
- Fix: Ensure the zone name in named.conf exactly matches the zone name defined in the SOA record within the zone file.
```
# In named.conf
zone "example.com" {
    type master;
    file "/etc/bind/zones/db.example.com";
};
```
  The SOA record in db.example.com must also start with example.com..
- Why it works: BIND uses the zone name to associate configuration with authoritative data. A mismatch means it can’t correctly link the zone definition to its data source.
Missing . at the end of FQDNs in Zone Files:
- Diagnosis: named-checkzone might complain about missing domain names or create unintended subdomains. For example, if ns1.example.com is written as ns1.example.com (without a trailing dot) and the $ORIGIN is example.com, BIND will interpret it as ns1.example.com.example.com.
- Fix: Always terminate fully qualified domain names (FQDNs) with a trailing dot (.) in zone files.
```
; Correct FQDNs
@   IN  NS  ns1.example.com.
ns1 IN  A   192.168.1.10
```
- Why it works: The trailing dot signifies the root of the DNS hierarchy. Without it, BIND appends the current $ORIGIN or the zone’s domain name, leading to incorrect FQDNs.

The next error you’ll likely encounter after fixing your BIND configuration is client @0.0.0.0 port 53: query: example.com IN A + E: REFUSED if your firewall is blocking port 53, or a "server failed" response if the DNS service itself is still encountering internal issues.