AdguardTeam/AdGuardHome · error

unmarshalling json data into aghalg.NullBool: bad value %q

Error message

unmarshalling json data into aghalg.NullBool: bad value %q

What it means

After successfully rebuilding the configuration manager, Refresh restarts all managed services via s.Start. This error means at least one service (DNS, DHCP, filtering, etc.) failed to initialize with the new configuration. The config was syntactically fine, but a service could not apply it at runtime.

Source

Thrown at internal/aghalg/nullbool.go:61

// MarshalJSON implements the json.Marshaler interface for NullBool.
func (nb NullBool) MarshalJSON() (b []byte, err error) {
	return []byte(nb.String()), nil
}

// type check
var _ json.Unmarshaler = (*NullBool)(nil)

// UnmarshalJSON implements the json.Unmarshaler interface for *NullBool.
func (nb *NullBool) UnmarshalJSON(b []byte) (err error) {
	if len(b) == 0 || bytes.Equal(b, []byte("null")) {
		*nb = NBNull
	} else if bytes.Equal(b, []byte("true")) {
		*nb = NBTrue
	} else if bytes.Equal(b, []byte("false")) {
		*nb = NBFalse
	} else {
		return fmt.Errorf("unmarshalling json data into aghalg.NullBool: bad value %q", b)
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check which service failed via the wrapped error and the service logs around the refresh
2. Verify no other process holds the needed ports (ss -tulpn | grep 53) and stop conflicts
3. Correct interface/port settings in the configuration and refresh again
4. Run the service with elevated privileges if binding privileged ports is required

// Pre-check port availability before refresh
if ln, err := net.Listen("tcp", ":53"); err != nil { return err } else { ln.Close() }

if err := svc.Refresh(ctx); err != nil {
    if strings.Contains(err.Error(), "restarting services") {
        // rollback config or retry after resolving port conflicts
    }
}

When it happens

Trigger: Calling Refresh when the new configuration is valid but a service cannot start under it: e.g. the DNS server cannot bind port 53, a DHCP server cannot bind its interface, or a filtering service cannot download/load its filters.

Common situations: Another process (systemd-resolved, dnsmasq, a second instance) already occupies the configured port; configuring a network interface that no longer exists; enabling a service whose data directory is missing or read-only.

Related errors

• duplicated values: %v
• json duration is nil
• parsing json time: %w
• json time is nil
• interface %s has no ipv4 addresses

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/3b56f1f3b3707ea9. Report an issue: GitHub.