TechnitiumSoftware/DnsServer · error · FormatException

Forwarder was not defined: {forwarderName}

Error message

Forwarder was not defined: {forwarderName}

What it means

Thrown while building an AdvancedForwardingApp Forwarding rule from the 'forwarders' array inside a forwarding definition. Each entry is a forwarder name that must exist in the top-level 'forwarders' map; if configForwarders is null or the name is missing, FormatException is raised.

Source

Thrown at Apps/AdvancedForwardingApp/App.cs:374

            IReadOnlyList<DnsForwarderRecordData> _forwarderRecords;
            readonly HashSet<string> _domains;

            #endregion

            #region constructor

            public Forwarding(JsonElement jsonForwarding, Dictionary<string, ConfigForwarder>? configForwarders)
            {
                JsonElement jsonForwarders = jsonForwarding.GetProperty("forwarders");
                List<DnsForwarderRecordData> forwarderRecords = new List<DnsForwarderRecordData>();

                foreach (JsonElement jsonForwarder in jsonForwarders.EnumerateArray())
                {
                    string forwarderName = jsonForwarder.ToString();

                    if ((configForwarders is null) || !configForwarders.TryGetValue(forwarderName, out ConfigForwarder? configForwarder))
                        throw new FormatException("Forwarder was not defined: " + forwarderName);

                    forwarderRecords.AddRange(configForwarder.ForwarderRecords);
                }

                _forwarderRecords = forwarderRecords;

                _domains = jsonForwarding.ReadArrayAsSet("domains") ?? [];
            }

            public Forwarding(IReadOnlyList<string> domains, NameServerAddress forwarder, bool dnssecValidation, ConfigProxyServer proxy)
                : this([GetForwarderRecord(forwarder, dnssecValidation, proxy)], domains)
            { }

            public Forwarding(IReadOnlyList<DnsForwarderRecordData> forwarderRecords, IReadOnlyList<string> domains)
            {
                _forwarderRecords = forwarderRecords;

                _domains = new HashSet<string>(domains.Count);

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Cross-check each name in the forwarding rule's 'forwarders' array against the keys of the top-level 'forwarders' object in dnsApp.config and fix typos.
2. If the top-level 'forwarders' block is missing, add it and define the referenced forwarder(s).
3. Keep forwarder names consistent when renaming by updating all referencing rules at the same time.

Example fix

// before (dnsApp.config)
"forwarders": { "google": { ... } },
"groups": [ { "forwarders": [ { "forwarders": [ "googl" ] } ] } ]
// after
"groups": [ { "forwarders": [ { "forwarders": [ "google" ] } ] } ]

HashSet<string> declared = configForwarders?.Keys.ToHashSet() ?? new HashSet<string>();
foreach (string name in ruleForwarderNames)
{
    if (!declared.Contains(name))
        throw new FormatException($"Forwarding rule references undefined forwarder '{name}'. Known: {string.Join(", ", declared)}.");
}

static bool IsForwarderDefined(string name, Dictionary<string, ConfigForwarder>? map) => map is not null && map.ContainsKey(name);

When it happens

Trigger: A forwarding rule references a forwarder name (string element of the rule's 'forwarders' array) that was never declared in the top-level 'forwarders' configuration object, or the 'forwarders' block itself was omitted so the map is null.

Common situations: Renaming a forwarder in the 'forwarders' block but forgetting to update references inside groups; a typo in the forwarder name; deleting the 'forwarders' block while keeping rules that use it.

Related errors

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

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