kea dhcp complains but starts up anyways: 'Failed to start DHCP Server with custom configurations. See Status > System Logs for more information about this failure.'

thearamadon

I'm running kea dhcp on pfsense CE 2.8.1. I have no custom DHCP json settings. Every time the DHCP server restarts (or is updated? unbound config changes trigger this too). I get an error notification saying

Failed to start DHCP Server with custom configurations. See Status > System Logs for more information about this failure.

System Log shows the following
(sorry for the terrible formatting. its not my fault!)

/services_unbound.php: The command '/usr/local/sbin/kea-dhcp4 -t /usr/local/etc/kea/kea-dhcp4.conf' returned exit code '1', the output was '2026-04-14 10:44:05.587 INFO [kea-dhcp4.hosts/36814.0x336630a12000] HOSTS_BACKENDS_REGISTERED the following host backend types are available: 2026-04-14 10:44:05.588 WARN [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_MT_DISABLED_QUEUE_CONTROL disabling dhcp queue control when multi-threading is enabled. 2026-04-14 10:44:05.588 WARN [kea-dhcp4.dhcp4/36814.0x336630a12000] DHCP4_RESERVATIONS_LOOKUP_FIRST_ENABLED Multi-threading is enabled and host reservations lookup is always performed first. 2026-04-14 10:44:05.589 INFO [kea-dhcp4.hooks/36814.0x336630a12000] HOOKS_LIBRARY_CLOSED hooks library /usr/local/lib/kea/hooks/libdhcp_lease_cmds.so successfully closed 2026-04-14 10:44:05.590 INFO [kea-dhcp4.hooks/36814.0x336630a12000] HOOKS_LIBRARY_CLOSED hooks library /usr/local/lib/kea/hooks/libdhcp_lease_options.so successfully closed 2026-04-14 10:44:05.590 INFO [kea-dhcp4.hooks/36814.0x336630a12000] HOOKS_LIBRARY_CLOSED hooks library /usr/local/lib/kea/hooks/libdhcp_run_script.so successfully closed 2026-04-14 10:44:05.594 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.7.0/24 with params: valid-lifetime=86400 2026-04-14 10:44:05.595 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.0.0/24 with params: valid-lifetime=86400 2026-04-14 10:44:05.597 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.1.0/24 with params: valid-lifetime=86400 2026-04-14 10:44:05.597 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.6.0/24 with params: valid-lifetime=86393 2026-04-14 10:44:05.597 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.17.0/24 with params: valid-lifetime=7200 2026-04-14 10:44:05.598 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.1.0.0/24 with params: valid-lifetime=7200 2026-04-14 10:44:05.598 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.8.0/24 with params: valid-lifetime=7200 2026-04-14 10:44:05.598 INFO [kea-dhcp4.dhcpsrv/36814.0x336630a12000] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 10.7.20.0/24 with params: valid-lifetime=7200 2026-04-14 10:44:05.598 ERROR [kea-dhcp4.dhcp4/36814.0x336630a12000] DHCP4_PARSER_FAIL failed to create or run parser for configuration element subnet4: option data does not match option definition (space: dhcp4, code: 12): no option value specified (/usr/local/etc/kea/kea-dhcp4.conf:1022:33) Error encountered: option data does not match option definition (space: dhcp4, code: 12): no option value specified (/usr/local/etc/kea/kea-dhcp4.conf:1022:33)'

If I look at /usr/local/etc/kea/kea-dhcp4.conf around that section, here is the config. Line 1022 is the { after "pools": [

        {
            "id": 8,
            "subnet": "10.7.20.0/24",
            "option-data": [
                {
                    "name": "domain-name-servers",
                    "data": "10.7.20.1"
                }
            ],
            "pools": [
                {
                    "pool": "10.7.20.10 - 10.7.20.12",
                    "client-class": "pool_opt4_0"
                }
            ],
            "reservations": [
                {
                    "hw-address": "68:05:ca:9b:d6:87",
                    "ip-address": "10.7.20.20",
                    "hostname": "pve-storage00",
                    "option-data": [
                        {
                            "name": "domain-name",
                            "data": "mydomain.tld"
                        }
                    ]
                },
            ],
            "reservations-in-subnet": true
        },

Any ideas why this is happening? The fact that kea ends up starting up anyways makes me think there's some race condition between pfsense setting up the config file and kea starting (the first time?)

Thanks!

tinfoilmatt

Can you screenshot the DHCP configuration for the interface containing subnet 10.7.20.0/24 and its only static reservation there? That appears to be the issue, more specifically the specified hostname (hence the logged "(space: dhcp4, code: 12)", with DHCP 'option 12' being host-name).

Per the docs, host-name/'option 12' shouldn't even be configured by an administator: https://kea.readthedocs.io/en/kea-3.0.0/arm/dhcp4-srv.html#id6. So there must be some special handling by pfSense happening, especially if you're making use of the Unbound integration/"DNS Early Registation" stuff.

tinfoilmatt

In fact, I think the "Early DNS Registration" setting specifically may be your smoking gun. Per the docs linked above:

Early DNS Registration:

Controls whether Kea will register hostnames from DHCP static mappings with the DNS Resolver at startup by default. The setting can be overridden on a per-interface basis in either direction.

When unchecked, Kea does not register the hostname until the client requests a DHCP lease.

With this setting enabled a client does not need to have DHCP enabled for its hostname to be available via the DNS Resolver. This was the default behavior of the ISC DHCP daemon when it performed DNS registration.

So I'm assuming, based on what you've shared, that that should be set to "Enable" for this interface?

thearamadon

Ah this one's on me. I had some json buried in a static mapping in that subnet that I was trying to use to disable the hostname from being sent out. Obviously kea didn't like that.

It would've been really helpful to see the contents of the file that was actually being used by kea when it failed to launch. It seems that as soon as it fails, pfsense reverts the file and restarts.