ruvnet/RuView · error · anyhow::Error

--hap-advertise-addr is required when HAP is enabled

Error message

--hap-advertise-addr is required when HAP is enabled

What it means

Anyhow error at HAP startup: HAP is enabled but --hap-advertise-addr was not provided. The address is required because MdnsSdAdvertiser is constructed with (hostname, advertise_addr) immediately after -- it is the IP HomeKit clients resolve via mDNS and connect to for pairing, and it cannot be guessed reliably on multi-interface machines.

Source

Thrown at v2/crates/homecore-server/src/hap.rs:78

            "HAP was requested but this binary was built without the `hap-server` feature"
        );
    }

    #[cfg(feature = "hap-server")]
    {
        use std::sync::Arc;

        use homecore_hap::{
            start_server, HapBridge, HapServerConfig, HapServiceRecord, MdnsSdAdvertiser,
            PairingStore,
        };

        let device_id = config
            .device_id
            .as_deref()
            .ok_or_else(|| anyhow::anyhow!("--hap-device-id is required when HAP is enabled"))?;
        let advertise_addr = config.advertise_addr.ok_or_else(|| {
            anyhow::anyhow!("--hap-advertise-addr is required when HAP is enabled")
        })?;
        if let Some(parent) = config.pairing_store.parent() {
            std::fs::create_dir_all(parent)?;
        }

        let advertiser = Arc::new(MdnsSdAdvertiser::new(
            config.hostname.clone(),
            advertise_addr,
        )?);
        let pairings = if config.pairing_store.exists() {
            if config.setup_code.is_some() {
                tracing::warn!(
                    "ignoring --hap-setup-code because the pairing store already exists"
                );
            }
            PairingStore::open(&config.pairing_store)?
        } else {
            let setup_code = config.setup_code.as_deref().ok_or_else(|| {

View on GitHub (pinned to 4685618388)

Solutions

1. Pass --hap-advertise-addr with the interface IP your HomeKit clients can reach (e.g. the host LAN IP, not 127.0.0.1)
2. In Docker, publish the HAP port and advertise the host's LAN address
3. On multi-NIC machines, verify reachability with ping/dig of the advertised mDNS hostname from the client device before pairing

Example fix

# before
./homecore-server --hap-enable --hap-device-id $DID
# error: --hap-advertise-addr is required when HAP is enabled

# after
./homecore-server --hap-enable --hap-device-id $DID --hap-advertise-addr 192.168.1.10

#!/usr/bin/env bash
LAN_IP=$(ip -4 -brief addr show scope global | awk '{print $3}' | cut -d/ -f1 | head -n1)
: "${LAN_IP:?could not determine advertise address}"
exec homecore-server --hap-enable --hap-advertise-addr "$LAN_IP" "$@"

fn hap_config_valid(cfg: &HapConfig) -> bool {
    cfg.enabled && cfg.advertise_addr.is_some()
}

When it happens

Trigger: Enabling HAP without --hap-advertise-addr; expecting the server to auto-detect its LAN IP (it does not); Docker/NAT setups where the container IP differs from the host IP reachable by the iPhone.

Common situations: Multi-NIC hosts (VPN + LAN + docker bridges) making auto-detection ambiguous; containers needing the host's LAN address, not the bridge IP; first-time setup following a partial example command.

Related errors

• --hap-device-id is required when HAP is enabled
• --hap-setup-code is required when creating a HAP pairing sto
• HAP was requested but this binary was built without the `hap
• cannot bind UDP socket on {addr}: {e}
• Rectangle requires 4 values: min_x,min_y,max_x,max_y (got {}

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/7458913d49010a9c. Report an issue: GitHub.