TechnitiumSoftware/DnsServer · warning · DnsServerException

Failed to generate unique label for the given domain name '{

Error message

Failed to generate unique label for the given domain name '{domain}'. Please try again.

What it means

CatalogZone.GetDomainWithLabel generates a random 8-byte label (Base32-hex encoded) and prepends it to a domain name to create a unique name under the catalog zone. It retries up to 10 times, checking NameExists each iteration. If all 10 attempts produce names that already exist, it throws DnsServerException. With 8 random bytes (2^64 possibilities) this should be cryptographically impossible under normal conditions — hitting it indicates either a bug in the RNG, extreme collision, or the NameExists check is malfunctioning.

Source

Thrown at DnsServerCore/Dns/Zones/CatalogZone.cs:386

        private string GetDomainWithLabel(string domain)
        {
            Span<byte> buffer = stackalloc byte[8];
            int i = 0;

            do
            {
                RandomNumberGenerator.Fill(buffer);
                string label = Base32.ToBase32HexString(buffer, true).ToLowerInvariant();
                string domainWithLabel = label + "." + domain;

                if (_dnsServer.AuthZoneManager.NameExists(_name, domainWithLabel))
                    continue;

                return domainWithLabel;
            }
            while (++i < 10);

            throw new DnsServerException("Failed to generate unique label for the given domain name '" + domain + "'. Please try again.");
        }

        #endregion

        #region public

        public override string GetZoneTypeName()
        {
            return "Catalog";
        }

        public override void SetRecords(DnsResourceRecordType type, IReadOnlyList<DnsResourceRecord> records)
        {
            switch (type)
            {
                case DnsResourceRecordType.SOA:
                    if ((records.Count != 1) || !records[0].Name.Equals(_name, StringComparison.OrdinalIgnoreCase))
                        throw new InvalidOperationException("Invalid SOA record.");

View on GitHub (pinned to d0484b6c1e)

Solutions

Retry the operation — the error message explicitly suggests this, and a new random draw will almost certainly succeed.
If it persists, check the catalog zone for corruption (orphaned entries that make NameExists malfunction).
Restart the DNS server process to reset the RNG state if a systemic RNG issue is suspected.
Investigate whether the catalog zone has an abnormally large number of entries that could increase collision probability (should not with 64-bit labels).

Example fix

// before (internal call fails 10 times)
catalogZone.AddMemberZone(domain);
// throws: Failed to generate unique label

// after (retry pattern)
for (int attempt = 0; attempt < 3; attempt++)
{
    try { catalogZone.AddMemberZone(domain); break; }
    catch (DnsServerException) when (attempt < 2) { continue; }
}

Defensive patterns

Strategy: retry

Try / catch

int maxRetries = 3;
for (int i = 0; i < maxRetries; i++)
{
    try { catalogZone.AddMemberZone(domain); break; }
    catch (DnsServerException ex) when (ex.Message.Contains("Failed to generate unique label") && i < maxRetries - 1)
        { continue; }
}

Prevention

Wrap catalog member-add operations in a retry loop (the error message explicitly says 'try again').
Monitor for persistent failures which indicate RNG or zone-state corruption.
Keep catalog zone member count reasonable to avoid edge-case collision scenarios.

When it happens

Trigger: Internally called when adding a new member zone to the catalog (generating a unique version label per RFC 9432 section 3.1). The exception fires if 10 consecutive random 8-byte labels all collide with existing names.

Common situations: Extremely unlikely under normal operation due to 64-bit randomness. Could occur if RandomNumberGenerator.Fill is broken/degraded, if the zone is in a corrupted state where NameExists always returns true, or in pathological test environments with mocked RNG. The error message says 'Please try again' implying a transient condition.

Related errors

AI-assisted analysis of TechnitiumSoftware/DnsServer@d0484b6c1e (2026-08-13). Data as JSON: /api/errors/e3452452de40e6fb. Report an issue: GitHub.