TechnitiumSoftware/DnsServer · error · FormatException

Groups array was not defined.

Error message

Groups array was not defined.

What it means

Thrown by the AdvancedForwardingApp initializer when the 'groups' property is absent or is not a JSON array. TryReadArrayAsMap returns false in that case, and since groups are mandatory the app throws FormatException and refuses to load.

Source

Thrown at Apps/AdvancedForwardingApp/App.cs:167

                return new Tuple<NetworkAddress, string>(networkAddress, jsonGroup.ToString());
            });

            if (jsonConfig.TryReadArrayAsMap("groups", ReadGroup, out Dictionary<string, Group>? groups) && (groups is not null))
            {
                if (_groups is not null)
                {
                    foreach (KeyValuePair<string, Group> group in _groups)
                    {
                        if (!groups.ContainsKey(group.Key))
                            group.Value.Dispose();
                    }
                }

                _groups = groups;
            }
            else
            {
                throw new FormatException("Groups array was not defined.");
            }

            return Task.CompletedTask;
        }

        public Task<DnsDatagram?> ProcessRequestAsync(DnsDatagram request, IPEndPoint remoteEP, DnsTransportProtocol protocol, bool isRecursionAllowed)
        {
            if (!_enableForwarding || !request.RecursionDesired)
                return Task.FromResult<DnsDatagram?>(null);

            IPAddress remoteIP = remoteEP.Address;
            NetworkAddress? network = null;
            string? groupName = null;

            foreach (KeyValuePair<NetworkAddress, string> entry in _networkGroupMap!)
            {
                if (entry.Key.Contains(remoteIP) && ((network is null) || (entry.Key.PrefixLength > network.PrefixLength)))
                {

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Add a 'groups' array to dnsApp.config with at least one group object (each group needs at least a name).
2. Confirm 'groups' is a JSON array (square brackets), not an object.
3. Regenerate the app config from the web UI or copy from the app's example/default config.

Example fix

// before (dnsApp.config)
{ "enableForwarding": true }
// after
{ "enableForwarding": true, "groups": [ { "name": "default", "forwarders": [] } ] }

if (!jsonConfig.TryGetProperty("groups", out JsonElement g) || g.ValueKind != JsonValueKind.Array || g.GetArrayLength() == 0)
    throw new FormatException("AdvancedForwardingApp requires a non-empty 'groups' JSON array.");

static bool HasValidGroups(JsonElement c) => c.TryGetProperty("groups", out JsonElement g) && g.ValueKind == JsonValueKind.Array && g.GetArrayLength() > 0;

When it happens

Trigger: Calling the AdvancedForwardingApp initializer with a config that omits the 'groups' array entirely, sets it to null, or provides an object/scalar instead of an array.

Common situations: Starting from a minimal config template that only defined 'forwarders'; deleting the groups block during manual editing; config corruption; upgrading from an older config schema that lacked groups.

Related errors

• Forwarder was not defined: {forwarderName}
• No 'forwarderAddresses' were configured.
• Unexpected URL format: {jsonUrl.ValueKind}
• Network group map contains an invalid network address: {netw
• Proxy server was not defined: {proxyName}

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