{"record":{"id":"1fc04b608266b481","repo":"ruvnet/RuView","slug":"hap-setup-code-is-required-when-creating-a-hap-p","errorCode":null,"errorMessage":"--hap-setup-code is required when creating a HAP pairing store","messagePattern":"--hap-setup-code is required when creating a HAP pairing store","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"v2/crates/homecore-server/src/hap.rs","lineNumber":97,"sourceCode":"        })?;\n        if let Some(parent) = config.pairing_store.parent() {\n            std::fs::create_dir_all(parent)?;\n        }\n\n        let advertiser = Arc::new(MdnsSdAdvertiser::new(\n            config.hostname.clone(),\n            advertise_addr,\n        )?);\n        let pairings = if config.pairing_store.exists() {\n            if config.setup_code.is_some() {\n                tracing::warn!(\n                    \"ignoring --hap-setup-code because the pairing store already exists\"\n                );\n            }\n            PairingStore::open(&config.pairing_store)?\n        } else {\n            let setup_code = config.setup_code.as_deref().ok_or_else(|| {\n                anyhow::anyhow!(\"--hap-setup-code is required when creating a HAP pairing store\")\n            })?;\n            PairingStore::create(\n                &config.pairing_store,\n                homecore_hap::SetupCode::parse(setup_code)?,\n                Some(device_id.to_owned()),\n            )?\n        };\n        let pairings = Arc::new(pairings);\n        let record =\n            HapServiceRecord::bridge(config.instance_name.clone(), bind_addr.port(), device_id);\n        let bridge = HapBridge::new(record);\n\n        let mut state_rx = hc.states().subscribe();\n        synchronize(&bridge, hc);\n        let sync_bridge = bridge.clone();\n        let sync_hc = hc.clone();\n        let state_task = tokio::spawn(async move {\n            loop {","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/ruvnet/RuView/blob/4685618388a5e49fad5b3005806f3bdd6a7c25c3/v2/crates/homecore-server/src/hap.rs#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","If the store should already exist, point --hap-pairing-store at the correct persisted path (mount the volume in containers)","Keep the pairing store on persistent storage so restarts open it instead of re-creating"],"exampleFix":"# before (first launch)\n./homecore-server --hap-enable --hap-device-id $DID --hap-advertise-addr 192.168.1.10\n# error: --hap-setup-code is required when creating a HAP pairing store\n\n# after\n./homecore-server --hap-enable --hap-device-id $DID --hap-advertise-addr 192.168.1.10 \\\n  --hap-setup-code 031-45-154 --hap-pairing-store /var/lib/homecore/pairings.json","handlingStrategy":"validation","validationCode":"#!/usr/bin/env bash\nPAIRING_STORE=/var/lib/homecore/pairings.json\nSETUP_ARGS=()\n[[ -f \"$PAIRING_STORE\" ]] || SETUP_ARGS=(--hap-setup-code 031-45-154)\nexec homecore-server --hap-enable --hap-pairing-store \"$PAIRING_STORE\" \"${SETUP_ARGS[@]}\" \"$@\"","typeGuard":"fn needs_setup_code(pairing_store: &std::path::Path) -> bool {\n    !pairing_store.exists()\n}","tryCatchPattern":null,"preventionTips":["Keep the pairing store on persistent storage so only the true first run needs a setup code","Include a valid-format setup code (XXX-XX-XXX) in first-boot provisioning scripts","Treat 'store not found' after a redeploy as a persistence bug (missing volume), not a flag omission"],"tags":["rust","cli","hap","homekit","pairing","first-run"],"backgroundTag":null,"analyzedSha":"4685618388a5e49fad5b3005806f3bdd6a7c25c3","analyzedAt":"2026-08-16T06:09:40.886Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}