DNS Publication Failures

DNS Publication Failures, in the admin app's System menu, answers one question: is DNS healthy on this server? A row means the panel holds records that the name servers are not serving. An empty page says Every zone on this server is published.

Publication runs in the background workers, so a failure there surfaces nowhere else by itself. This is also the only place where a whole-server failure reads as one problem: a rotated API key is a row per zone, and a list ordered by last occurrence puts them together, where each zone's own page would tell a different account holder the same thing.

Zones Behind

Above the failures, Zones Behind lists zones that hold changes the name servers were never given, and for which nothing failed anywhere the panel could record it: the zone, how many record sets are waiting, and the oldest change. A zone is listed once a record set has been pending for five minutes.

This is what a stopped worker, a worker holding a stale container after an upgrade, or a trigger dropped on the way to the outbox look like: the failure happens before anything can be logged, and every zone quietly falls behind. Check that the panel's workers (elpan-panel-worker@* and elpan-panel-async@*) are running. Once they are, the five-minute pass (dns publish-pending) catches up by itself, or dns republish converges everything at once.

A zone on the Manual update backend is never listed here: its outstanding rows are its owner's to-do list, not a fault, and they would sit on this page for ever. The owner sees them on their own zone page, in the vocabulary that fits (DNS backends).

The failures

Each row is one problem between the panel and a backend, for as long as it is one:

Column	What it holds
Zone	Linked to the zone's service. Deleted when the panel no longer has the zone and the backend is still serving it (a failed teardown).
Kind	Whose problem it is (below).
Operation	Publishing records, Applying zone settings, Republishing the zone, Removing the zone or Reading zone state.
Record	The record set the failure was about, as name type. Empty when the operation was about the whole zone, or a batch covered several names.
Backend	The backend's identifier: builtin on an ordinary install, else powerdns, cloudflare, desec.
Message	The backend's own words, with any secret the configuration held redacted, and the exception class under it. A TypeError about a constructor argument is a stale worker, every time.
Since, Occurrences	A row coalesces every repetition of one problem, so "since 14:02, 340 times" is one row. That is also what tells a flapping backend from a permanently refused value.

A later success resolves the rows it is evidence about, and only those: publishing www says nothing about a LOC record at hq that has been refused for a week. Resolved rows leave the page and are kept 30 days; an open one stays however old, because a record refused six weeks ago is still refused. A zone holds at most 100 open problems; past that it has one problem, its backend.

The four kinds

Kind	Meaning	Retried	Who acts
Backend unavailable	The backend is down, slow, restarting, or answered 5xx. Also everything a driver did not classify.	Yes; usually the retry works.	You, when it lasts.
Rejected by the DNS server	The backend refused this value and will refuse it again.	No. The row is the durable record; dns republish is the repair once the value changes.	The account holder, who typed the value.
Backend credentials refused	The key or token in the zone's backend configuration is not the backend's.	Yes: the next delivery opens a connection with whatever credential is on disk by then.	You for the built-in backend; the account holder for a hosted one.
Backend misconfigured	The install has no usable default backend at all. Every zone has it.	Yes.	You.

What the account holder sees

Only a refusal shows the account holder the backend's message, on the record it is about and in the zone's Publication Issues tab. For every other kind their page says Publication is delayed. The server operator has been notified.; the endpoints and exception classes are yours alone.

A refusal that has stood for an hour is also mailed to the account holder, once per problem, by an hourly pass; a new problem is a new row and gets its own notice. The same pass emits a dns.publication_failed event for the server's Webhooks.

elpanctl dns error-log notify

runs that pass now. It sends real mail; there is no dry run, because the screen already answers who would be told.

Common causes

You see	Likely cause	What to do
Backend unavailable, builtin, a burst of occurrences	The name server (the elpan-dns container) is down or restarting. For about six seconds after its API key is rewritten it refuses the new key too.	Check that the name server is running; the deliveries are retried and the next one lands.
Backend credentials refused, builtin	The PowerDNS API key was rotated under long-running workers.	Nothing: the built-in backend mints the key itself, and the retry that follows opens its connection with the fresh key.
Backend credentials refused, cloudflare or desec	The account holder's API token was revoked or changed at the provider.	They re-enter it on the zone's Backend card; the panel verifies it against the provider before storing it.
Rejected by the DNS server, one record	A value the panel accepted and the backend renders differently or does not take. The message quotes the format it wanted.	Fix or remove the record, then dns republish <zone>.
Zones Behind growing across every zone, no failures	The workers are stopped, or hold a stale container after an upgrade.	Restart elpan-panel-worker@* and elpan-panel-async@*, then dns republish.

Housekeeping

elpanctl dns error-log prune

Drops resolved rows older than 30 days and trims any zone holding more than 100 open ones. A nightly task runs the same prune; the command exists so its effect can be observed by hand.

Where to look next

A record that looks wrong while nothing is waiting and nothing has failed means the panel believes it has published. dns inspect <zone> <name> <type> reads both sides and says whether they agree; see How DNS publication works.