TechnitiumSoftware/DnsServer · error · ArgumentException

Cluster node URL length must be less than 255 bytes.

Error message

Cluster node URL length must be less than 255 bytes.

What it means

Constructor argument guard on the explicit ClusterNode(ClusterManager, int, Uri, IReadOnlyList<IPAddress>, ...) overload. It rejects a URL whose originalString exceeds 255 characters. The 255 cap exists because ClusterNode.WriteTo() serializes the URL via BinaryWriter.WriteShortString(), which uses a single-byte length prefix (max 255 bytes), so a longer URL would corrupt the on-disk cluster config. Note the check is '> 255', so values 0..255 are accepted even though the message says 'less than 255'.

Source

Thrown at DnsServerCore/Cluster/ClusterNode.cs:98

            _url = nodeInfo.Url;
            _ipAddresses = nodeInfo.IPAddresses.Convert(IPAddress.Parse);
            _type = Enum.Parse<ClusterNodeType>(nodeInfo.Type, true);

            if (_type == ClusterNodeType.Primary)
            {
                _lastSeen = DateTime.UtcNow;
                _state = ClusterNodeState.Connected; //since this info was received from primary node
            }
            else
            {
                _state = ClusterNodeState.Unknown;
            }
        }

        public ClusterNode(ClusterManager clusterManager, int id, Uri url, IReadOnlyList<IPAddress> ipAddresses, ClusterNodeType type, ClusterNodeState state)
        {
            if (url.OriginalString.Length > 255)
                throw new ArgumentException("Cluster node URL length must be less than 255 bytes.", nameof(url));

            if (!url.Scheme.Equals("https", StringComparison.OrdinalIgnoreCase))
                throw new ArgumentException("Cluster node URL must use HTTPS scheme.", nameof(url));

            if (ipAddresses.Count > 10)
                throw new ArgumentException("Cluster node cannot have more than 10 IP addresses.", nameof(ipAddresses));

            _clusterManager = clusterManager;

            _id = id;
            _url = url;
            _ipAddresses = ipAddresses;
            _type = type;
            _state = state;
        }

        public ClusterNode(ClusterManager clusterManager, BinaryReader bR)
        {

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Shorten the node's domain name so the full https://host:port/ URL stays within 255 characters.
2. Strip any path/query/fragment from the URL before constructing the node (cluster node URLs are root paths).
3. If you control the host naming, use a shorter subdomain or drop unnecessary labels.
4. Validate url.OriginalString.Length before instantiating ClusterNode.

Example fix

// before
var url = new Uri("https://really-long-hostname-with-many-labels.example.com:5380/some/long/path?x=1");
var node = new ClusterNode(mgr, id, url, ips, type, state); // throws [201]

// after: bare root URL, short host
var url = new Uri("https://ns1.example.com:5380/");
if (url.OriginalString.Length > 255) throw new InvalidOperationException("URL too long");
var node = new ClusterNode(mgr, id, url, ips, type, state);

static void ValidateClusterNodeUrl(Uri url)
{
    ArgumentNullException.ThrowIfNull(url);
    if (url.OriginalString.Length > 255)
        throw new ArgumentException("Cluster node URL must be <= 255 chars.", nameof(url));
}

ValidateClusterNodeUrl(url);
var node = new ClusterNode(mgr, id, url, ips, type, state);

static bool IsValidClusterNodeUrl(Uri url) =>
    url is not null && url.OriginalString.Length <= 255;

When it happens

Trigger: Calling the 5-parameter ClusterNode constructor with a Uri whose originalString is 256+ characters — e.g. an extremely long FQDN, an unusual port, or a URL carrying a long path/query suffix.

Common situations: A very long fully-qualified domain name used as the cluster node URL; accidentally appending a path or query string to the node URL; copy-paste of a full management-UI URL instead of the bare https://host:port/ form.

Related errors

• Cluster node URL must use HTTPS scheme.
• Cluster node cannot have more than 10 IP addresses.
• Display name length cannot exceed 255 characters.
• DNS Server Cluster config file format is invalid.
• DNS Server Cluster config version not supported.

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