ruvnet/RuView · error · anyhow::Error

--hap-setup-code is required when creating a HAP pairing sto

Error message

--hap-setup-code is required when creating a HAP pairing store

What it means

Anyhow error on first HAP launch: the pairing-store file at config.pairing_store does not exist, so the server must create it via PairingStore::create, which requires a setup code for initial HomeKit pairing (parsed by SetupCode::parse). On later launches the existing store is simply opened, and a supplied --hap-setup-code is ignored with a warning -- the error only fires when the store is being created.

Source

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

        })?;
        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(|| {
                anyhow::anyhow!("--hap-setup-code is required when creating a HAP pairing store")
            })?;
            PairingStore::create(
                &config.pairing_store,
                homecore_hap::SetupCode::parse(setup_code)?,
                Some(device_id.to_owned()),
            )?
        };
        let pairings = Arc::new(pairings);
        let record =
            HapServiceRecord::bridge(config.instance_name.clone(), bind_addr.port(), device_id);
        let bridge = HapBridge::new(record);

        let mut state_rx = hc.states().subscribe();
        synchronize(&bridge, hc);
        let sync_bridge = bridge.clone();
        let sync_hc = hc.clone();
        let state_task = tokio::spawn(async move {
            loop {

View on GitHub (pinned to 4685618388)

Solutions

1. On first launch pass --hap-setup-code with a HomeKit-format code (e.g. '031-45-154' -- SetupCode::parse validates the format); it is only needed until the store exists
2. If the store should already exist, point --hap-pairing-store at the correct persisted path (mount the volume in containers)
3. Keep the pairing store on persistent storage so restarts open it instead of re-creating

Example fix

# before (first launch)
./homecore-server --hap-enable --hap-device-id $DID --hap-advertise-addr 192.168.1.10
# error: --hap-setup-code is required when creating a HAP pairing store

# after
./homecore-server --hap-enable --hap-device-id $DID --hap-advertise-addr 192.168.1.10 \
  --hap-setup-code 031-45-154 --hap-pairing-store /var/lib/homecore/pairings.json

#!/usr/bin/env bash
PAIRING_STORE=/var/lib/homecore/pairings.json
SETUP_ARGS=()
[[ -f "$PAIRING_STORE" ]] || SETUP_ARGS=(--hap-setup-code 031-45-154)
exec homecore-server --hap-enable --hap-pairing-store "$PAIRING_STORE" "${SETUP_ARGS[@]}" "$@"

fn needs_setup_code(pairing_store: &std::path::Path) -> bool {
    !pairing_store.exists()
}

When it happens

Trigger: First run with HAP enabled and no --hap-setup-code; the pairing-store path changed (new volume, container without the persisted store, different user/home) so an existing store is not found and the run looks like a first launch; deleting the store file to reset pairings and restarting without a code.

Common situations: Containers/VMs without a persistent volume for the pairing store wiping it every restart; the setup code added to unit files only after the first failed boot; admins clearing the store to un-pair and forgetting the flag.

Related errors

• --hap-device-id is required when HAP is enabled
• --hap-advertise-addr is required when HAP is enabled
• HAP was requested but this binary was built without the `hap
• Rectangle requires 4 values: min_x,min_y,max_x,max_y (got {}
• Circle requires 3 values: center_x,center_y,radius (got {})

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