fix: Network fails to start if a stale network descriptor is present (#466)

* fix: Network fails to start if a stale network descriptor is present

* changelog

* fmt

* fix: simplify stale descriptor cleanup and fix ordering

Clean port descriptor before project descriptor so the global resource
is freed first. Pass gateway_port() directly since cleanup_port_descriptor
already handles None.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Linwei Shang <linwei.shang@dfinity.org>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Unreleased
 
 * feat: Many more commands support `--json` and `--quiet`.
+* fix: Network would fail to start if a stale descriptor was present
 
 # v0.2.1
 

crates/icp-cli/src/commands/network/start.rs

@@ -15,7 +15,7 @@ use icp::{
     },
     settings::Settings,
 };
-use tracing::{debug, info};
+use tracing::{debug, info, warn};
 
 use super::args::NetworkOrEnvironmentArgs;
 use icp::context::Context;
@@ -78,8 +78,23 @@ pub(crate) async fn exec(ctx: &Context, args: &StartArgs) -> Result<(), anyhow::
     nd.ensure_exists()
         .context("failed to create network directory")?;
 
-    if nd.load_network_descriptor().await?.is_some() {
-        bail!("network '{}' is already running", network.name);
+    if let Some(descriptor) = nd.load_network_descriptor().await? {
+        debug!(
+            "Found network descriptor for {} in: {}",
+            nd.network_name, nd.network_root
+        );
+        if descriptor.child_locator.is_alive().await {
+            bail!("network '{}' is already running", network.name);
+        } else {
+            warn!(
+                "Found stale network descriptor for '{}' (process is no longer running). \
+                 Cleaning up and starting fresh.",
+                network.name
+            );
+            nd.cleanup_port_descriptor(descriptor.gateway_port())
+                .await?;
+            nd.cleanup_project_network_descriptor().await?;
+        }
     }
 
     // Clean up any existing canister ID mappings of which environment is on this network

crates/icp-cli/tests/canister_install_tests.rs

@@ -479,7 +479,7 @@ async fn canister_install_with_environment_settings_override() {
                 - type: script
                   command: cp '{wasm}' "$ICP_WASM_OUTPUT_PATH"
             settings:
-              memory_allocation: 1073741824
+              memory_allocation: 10485760
 
         {NETWORK_RANDOM_PORT}
 
@@ -488,7 +488,7 @@ async fn canister_install_with_environment_settings_override() {
             network: random-network
             settings:
               my-canister:
-                memory_allocation: 2147483648
+                memory_allocation: 20971520
     "#};
 
     write_string(&project_dir.join("icp.yaml"), &pm).expect("failed to write project manifest");
@@ -497,7 +497,7 @@ async fn canister_install_with_environment_settings_override() {
     let _g = ctx.start_network_in(&project_dir, "random-network").await;
     ctx.ping_until_healthy(&project_dir, "random-network");
 
-    // Deploy should use the environment override (memory_allocation: 2GB)
+    // Deploy should use the environment override (memory_allocation: 20MiB)
     clients::icp(&ctx, &project_dir, Some("random-environment".to_string()))
         .mint_cycles(10 * TRILLION);
 
@@ -532,8 +532,8 @@ async fn canister_install_with_environment_settings_override() {
 
     let output_str = String::from_utf8_lossy(&output);
     assert!(
-        output_str.contains("Memory allocation: 2_147_483_648"),
-        "Expected memory_allocation to be 2_147_483_648 (2GB) from environment override, got: {}",
+        output_str.contains("Memory allocation: 20_971_520"),
+        "Expected memory_allocation to be 20_971_520 (20MiB) from environment override, got: {}",
         output_str
     );
 }

crates/icp-cli/tests/network_tests.rs

@@ -874,3 +874,74 @@ async fn network_gateway_binds_to_configured_interface() {
         resp.status()
     );
 }
+
+#[tokio::test]
+async fn network_recovers_from_stale_descriptor() {
+    let ctx = TestContext::new();
+    let project_dir = ctx.create_project_dir("stale-descriptor");
+
+    // Project manifest
+    write_string(&project_dir.join("icp.yaml"), NETWORK_RANDOM_PORT)
+        .expect("failed to write project manifest");
+
+    // Ensure the network descriptor directory exists
+    let network_dir = project_dir.join(".icp/cache/networks/random-network");
+    std::fs::create_dir_all(&network_dir).expect("failed to create network directory");
+
+    // Create a stale descriptor with a PID that cannot exist
+    let stale_descriptor = serde_json::json!({
+        "v": "1",
+        "id": "11111111-1111-1111-1111-111111111111",
+        "project-dir": project_dir.to_string(),
+        "network": "random-network",
+        "network-dir": network_dir.to_string(),
+        "gateway": {
+            "fixed": false,
+            "port": 9999,
+            "host": "localhost",
+            "ip": "127.0.0.1"
+        },
+        "child-locator": {
+            "type": "pid",
+            "pid": u32::MAX,  // Non-existent PID
+            "start-time": 0
+        },
+        "root-key": "308182301c300d06092a864886f70d0101010500030b008081007f",
+        "pocketic-config-port": null,
+        "pocketic-instance-id": null,
+        "candid-ui-canister-id": null,
+        "proxy-canister-id": null,
+        "status-dir": null,
+        "use-friendly-domains": false
+    });
+
+    // Write the stale descriptor
+    let descriptor_bytes =
+        serde_json::to_vec(&stale_descriptor).expect("failed to serialize descriptor");
+    ctx.write_network_descriptor(&project_dir, "random-network", &descriptor_bytes);
+
+    // Start network - should succeed and clean up the stale descriptor
+    ctx.icp()
+        .current_dir(&project_dir)
+        .args(["network", "start", "random-network", "--background"])
+        .assert()
+        .success()
+        .stderr(contains("Found stale network descriptor"));
+
+    // Verify the network actually started (descriptor should be updated with real process)
+    let network = ctx.wait_for_network_descriptor(&project_dir, "random-network");
+
+    ctx.ping_until_healthy(&project_dir, "random-network");
+
+    // Verify we can query the network
+    let agent = ic_agent::Agent::builder()
+        .with_url(format!("http://127.0.0.1:{}", network.gateway_port))
+        .build()
+        .expect("Failed to build agent");
+
+    let status = agent.status().await.expect("Failed to get network status");
+    assert!(
+        matches!(&status.replica_health_status, Some(health) if health == "healthy"),
+        "Network should be healthy"
+    );
+}