TechnitiumSoftware/DnsServer · error · InvalidOperationException

MaxMind database not initialized.

Error message

MaxMind database not initialized.

What it means

Thrown by GeoContinentApp Address.ProcessRequestAsync in the A/AAAA branch when the _maxMind singleton is null. The app lazily relies on a MaxMind database reader that is constructed during app initialisation; if construction failed (file missing, see error 28) the field stays null and any geo lookup raises InvalidOperationException.

Source

Thrown at Apps/GeoContinentApp/Address.cs:170

            else
            {
                _groups = new Dictionary<string, List<string>>();
            }
        }

        public Task<DnsDatagram?> ProcessRequestAsync(DnsDatagram request, IPEndPoint remoteEP, DnsTransportProtocol protocol, bool isRecursionAllowed, string zoneName, string appRecordName, uint appRecordTtl, string appRecordData)
        {
            DnsQuestionRecord question = request.Question[0];

            if (!question.Name.Equals(appRecordName, StringComparison.OrdinalIgnoreCase) && !appRecordName.StartsWith('*'))
                return Task.FromResult<DnsDatagram?>(null);

            switch (question.Type)
            {
                case DnsResourceRecordType.A:
                case DnsResourceRecordType.AAAA:
                    if (_maxMind is null)
                        throw new InvalidOperationException("MaxMind database not initialized.");

                    using (JsonDocument jsonDocument = JsonDocument.Parse(appRecordData, _jsonParseOptions))
                    {
                        JsonElement jsonAppRecordData = jsonDocument.RootElement;
                        JsonElement jsonContinent = default;

                        byte scopePrefixLength = 0;
                        EDnsClientSubnetOptionData requestECS = request.GetEDnsClientSubnetOption();
                        if (requestECS is not null)
                        {
                            long? asn = null;

                            if ((_maxMind.IspReader is not null) && _maxMind.IspReader.TryIsp(requestECS.Address, out IspResponse? csIsp) && (csIsp.Network is not null))
                            {
                                scopePrefixLength = (byte)csIsp.Network.PrefixLength;
                                asn = csIsp.AutonomousSystemNumber;
                            }
                            else if ((_maxMind.AsnReader is not null) && _maxMind.AsnReader.TryAsn(requestECS.Address, out AsnResponse? csAsn) && (csAsn.Network is not null))

View on GitHub (pinned to d0484b6c1e)

Solutions

  1. Download GeoLite2-Country.mmdb (or GeoIP2-Country.mmdb) from MaxMind and place it in the DNS server ApplicationFolder.
  2. Restart the DnsServer service so the GeoContinentApp MaxMind constructor succeeds and _maxMind is populated.
  3. Check the startup log for the companion error 'MaxMind Country file is missing!' (error 28) to confirm the root cause.
Defensive patterns

Strategy: try-catch

Validate before calling

if (_maxMind is null)
    _log.Warn("GeoContinentApp A/AAAA query for {0} skipped: MaxMind database not loaded (place GeoLite2-Country.mmdb in the application folder).", appRecordName);

Try / catch

try { return await ProcessContinentAsync(request, ...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("MaxMind database not initialized"))
{ _log.Error("GeoIP database missing — see error 'MaxMind Country file is missing!'"); return Task.FromResult<DnsDatagram?>(null); }

Prevention

When it happens

Trigger: A DNS A/AAAA query matches a GeoContinentApp record, but the MaxMind instance was never created — typically because the GeoLite2-Country.mmdb / GeoIP2-Country.mmdb file was absent at startup, so the MaxMind constructor threw and _maxMind remained null.

Common situations: Fresh install without the GeoIP database files deployed, files moved or renamed, or the application folder changed. The symptom is that continent-based answers never work.

Related errors

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