ruvnet/RuView · error · anyhow::Error

--hap-device-id is required when HAP is enabled

Error message

--hap-device-id is required when HAP is enabled

What it means

Anyhow error at HAP startup: HAP is enabled and compiled in, but config.device_id is None because --hap-device-id was not supplied. The device_id is load-bearing downstream -- it is persisted into the PairingStore at creation and embedded in the HAP service record (HapServiceRecord::bridge(..., device_id)) that HomeKit clients use to identify the bridge, so startup refuses to invent one.

Source

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

        let _ = (hc, bind_addr);
        anyhow::bail!(
            "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)?

View on GitHub (pinned to 4685618388)

Solutions

1. Pass a stable unique --hap-device-id (e.g. a generated UUID v4) when enabling HAP
2. Persist the same ID across restarts (config file or provisioning script) -- changing it later invalidates existing pairings because the bridge identity changes
3. Generate one with uuidgen and store it alongside the pairing store path in your deployment config

Example fix

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

# after
./homecore-server --hap-enable --hap-advertise-addr 192.168.1.10 \
  --hap-device-id 6f1d2b34-9c8e-4a5d-b0f1-7e2c3d4a5b6c

#!/usr/bin/env bash
: "${HAP_DEVICE_ID:?HAP_DEVICE_ID must be set (uuidgen)}"
exec homecore-server --hap-enable --hap-device-id "$HAP_DEVICE_ID" "$@"

fn hap_config_valid(cfg: &HapConfig) -> bool {
    cfg.enabled && cfg.device_id.as_deref().is_some_and(|id| !id.trim().is_empty())
}

When it happens

Trigger: Enabling HAP flags but omitting --hap-device-id; passing an empty string for the flag (Option stays effectively unusable for the record); config files copied from examples without filling in the ID.

Common situations: First-time HAP setup following a guide that skips the ID argument; scripts templated per-host where one host is missing the variable; containerized deployments losing the argument in env-to-flag translation.

Related errors

• --hap-advertise-addr 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
• HOMECORE_TOKENS is required; use --insecure-dev-auth only fo
• invalid automations file {}: {e}

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