{"record":{"id":"4f2faa383187bd26","repo":"neondatabase/neon","slug":"failed-to-check-node-status-e","errorCode":null,"errorMessage":"Failed to check node status: {e}","messagePattern":"Failed to check node status: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"control_plane/src/pageserver.rs","lineNumber":336,"sourceCode":"                self.conf.id, datadir,\n            )\n        })?;\n        let args = vec![\"-D\", datadir_path_str];\n\n        background_process::start_process(\n            \"pageserver\",\n            &datadir,\n            &self.env.pageserver_bin(),\n            args,\n            self.pageserver_env_variables()?,\n            background_process::InitialPidFile::Expect(self.pid_file()),\n            retry_timeout,\n            || async {\n                let st = self.check_status().await;\n                match st {\n                    Ok(()) => Ok(true),\n                    Err(mgmt_api::Error::ReceiveBody(_)) => Ok(false),\n                    Err(e) => Err(anyhow::anyhow!(\"Failed to check node status: {e}\")),\n                }\n            },\n        )\n        .await?;\n\n        Ok(())\n    }\n\n    fn pageserver_env_variables(&self) -> anyhow::Result<Vec<(String, String)>> {\n        // FIXME: why is this tied to pageserver's auth type? Whether or not the safekeeper\n        // needs a token, and how to generate that token, seems independent to whether\n        // the pageserver requires a token in incoming requests.\n        Ok(if self.conf.http_auth_type != AuthType::Trust {\n            // Generate a token to connect from the pageserver to a safekeeper\n            let token = self\n                .env\n                .generate_auth_token(&Claims::new(None, Scope::SafekeeperData))?;\n            vec![(\"NEON_AUTH_TOKEN\".to_owned(), token)]","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/neondatabase/neon/blob/8f60b04da47ffefe0e52bda2440134b42874eb75/control_plane/src/pageserver.rs#L318-L354","documentation":"While waiting for a locally started pageserver, neon_local polls GET /v1/status on its management HTTP API. Only mgmt_api::Error::ReceiveBody is treated as not-yet-ready and retried until retry_timeout; every other failure — SendRequest (request could not be sent/connect failed), ApiError (an HTTP error status such as 401 or 503), or a malformed error body — aborts the start immediately with this message.","triggerScenarios":"The pageserver's HTTP endpoint answers the status probe with an error status (401 when JWT auth is configured but neon_local sends no/wrong token, 503 while internal services initialize) or the management API request fails at the send/connect level in a non-retryable way.","commonSituations":"Auth-type mismatch between the neon config and neon_local's token generation, a port collision making another service answer on listen_http_addr, or a pageserver that crashes mid-startup.","solutions":["Check <base>/pageserver_<id>/pageserver.log and the neon_local output for the underlying mgmt_api error (status code and body)","Verify listen_http_addr is the port being polled and that nothing else binds it","If JWT auth is enabled, ensure neon_local generated/loaded the matching private key; or use http_auth_type = trust for local runs","Retry the start once transient causes (slow init, port races) are ruled out"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// before start: catch the common fatal cause early\nif ps_conf.http_auth_type != AuthType::Trust {\n    anyhow::ensure!(\n        env.get_private_key_path().exists(),\n        \"JWT auth enabled but the env has no private key\"\n    );\n}","typeGuard":null,"tryCatchPattern":"match ps.check_status().await {\n    Ok(()) => {}\n    Err(mgmt_api::Error::ReceiveBody(_)) => { /* still starting: keep polling within retry_timeout */ }\n    Err(mgmt_api::Error::ApiError(status, body)) => {\n        // 401/403 => fix auth; 503 => keep waiting; inspect `body`\n    }\n    Err(other) => { /* send/connect problem: check port, process, pageserver.log */ }\n}","preventionTips":["Pin listen_http_addr ports per env to avoid collisions","Keep http_auth_type = trust for local dev unless keys are also provisioned","Read pageserver.log first — the mgmt error usually mirrors a startup failure"],"tags":["rust","neon-local","pageserver","http","startup","auth"],"backgroundTag":"service-health-check-failed","analyzedSha":"8f60b04da47ffefe0e52bda2440134b42874eb75","analyzedAt":"2026-08-16T23:39:28.135Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}