{"record":{"id":"c75005de586540d4","repo":"astrid-runtime/astrid","slug":"native-local-uplink-listener-is-unavailable","errorCode":null,"errorMessage":"native local uplink listener is unavailable","messagePattern":"native local uplink listener is unavailable","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"critical","filePath":"crates/astrid-daemon/src/lib.rs","lineNumber":298,"sourceCode":"    if defer_logging {\n        init_logging(&log_config);\n    }\n    kernel\n        .set_system_capsules(\n            unified_cfg\n                .as_ref()\n                .into_iter()\n                .flat_map(|config| config.uplinks.iter())\n                .map(|uplink| uplink.plugin.clone()),\n        )\n        .await;\n\n    // Astrid owns its baseline control plane. Start it before loading optional\n    // distribution capsules so no capsule can race the canonical listener or\n    // make a clean runtime unbootable by being absent or broken.\n    let native_listener = kernel\n        .claim_native_uplink_listener()\n        .ok_or_else(|| anyhow::anyhow!(\"native local uplink listener is unavailable\"))?;\n    let native_uplink_task = astrid_uplink::native::NativeUplink {\n        listener: native_listener,\n        session_token: std::sync::Arc::clone(&kernel.session_token),\n        home: astrid_home.clone(),\n        event_bus: std::sync::Arc::clone(&kernel.event_bus),\n        shutdown: kernel.shutdown_tx.subscribe(),\n    }\n    .spawn();\n\n    // In ephemeral mode, shut down immediately when the last client disconnects.\n    if args.ephemeral {\n        kernel.set_ephemeral(true);\n    }\n\n    // Load the boot-critical default view. Non-default profile principals warm\n    // after readiness so a large tenant set cannot make daemon restart health\n    // wait on every agent's capsule view.\n    kernel.load_boot_capsules().await;","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-daemon/src/lib.rs#L280-L316","documentation":"The daemon claims the kernel's native local uplink listener via `kernel.claim_native_uplink_listener()`; the API returns Option and None means the baseline control-plane socket could not be provided. Because Astrid owns its baseline control plane and must start it before loading any distribution capsules, a missing listener is fatal.","triggerScenarios":"Calling daemon `run()` when `claim_native_uplink_listener()` returns None — typically the kernel failed to create/bind the canonical local listener (socket setup failure, resource exhaustion, or it was already claimed).","commonSituations":"Another astrid process already bound the canonical listener; OS-level socket limits or sandbox restrictions preventing listener creation on the platform.","solutions":["Check for and stop another running astrid daemon instance holding the listener.","Verify the platform supports the local listener (unix socket availability) and no sandbox blocks socket creation.","Restart the daemon; if None persists on a clean environment, report it as an internal invariant violation with logs."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// rust\nmatch daemon::run(args).await {\n    Err(e) if e.to_string().contains(\"uplink listener\") => {\n        eprintln!(\"another daemon may hold the uplink listener: {e:#}\");\n        std::process::exit(1);\n    }\n    Err(e) => { eprintln!(\"{e:#}\"); std::process::exit(1); }\n    Ok(()) => {}\n}","preventionTips":["Run only one astrid daemon per workspace/home.","Use pidfiles or supervisor single-instance options to prevent duplicate daemons.","Check socket availability and sandbox settings on constrained platforms."],"tags":["network","listener","startup"],"backgroundTag":"internal-invariant-violation","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}