{"record":{"id":"dfb78adb7a0d6ddb","repo":"risingwavelabs/risingwave","slug":"failed-to-start-a-new-session-0","errorCode":null,"errorMessage":"Failed to start a new session: {0}","messagePattern":"Failed to start a new session: (.+?)","errorType":"error_code","errorClass":"PsqlError","httpStatus":null,"severity":"error","filePath":"src/utils/pgwire/src/error.rs","lineNumber":27,"sourceCode":"// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nuse std::fmt;\nuse std::io::Error as IoError;\n\nuse risingwave_common::error::code::PostgresErrorCode;\nuse thiserror::Error;\n\nuse crate::pg_server::BoxedError;\npub type PsqlResult<T> = std::result::Result<T, PsqlError>;\n\n/// Error type used in pgwire crates.\n#[derive(Error, Debug)]\npub enum PsqlError {\n    #[error(\"Failed to start a new session: {0}\")]\n    StartupError(\n        #[source]\n        #[backtrace]\n        BoxedError,\n    ),\n\n    #[error(\"Invalid password\")]\n    PasswordError,\n\n    #[error(\"Protocol violation: {0}\")]\n    ProtocolError(\n        #[source]\n        #[backtrace]\n        ProtocolViolationError,\n    ),\n\n    #[error(\"Failed to run the query: {0}\")]\n    SimpleQueryError(","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/utils/pgwire/src/error.rs#L9-L45","documentation":"pgwire wraps any error that occurs while establishing a new client session (startup/authentication phase) into PsqlError::StartupError with this display message. The boxed source error carries the actual cause. It is thrown by the pgwire session bootstrap path before query handling begins.","triggerScenarios":"Any failure during the PostgreSQL startup packet handling in pgwire: TLS negotiation failure, invalid startup parameters, database/user resolution errors, or an underlying frontend/rw error raised before the session loop starts.","commonSituations":"Client connects with unsupported sslmode or protocol version; unknown database name at startup; frontend service unavailable when the session is created; corrupted or hostile startup messages.","solutions":["Read the #[source] BoxedError of PsqlError::StartupError for the concrete root cause.","Check client connection parameters (database name, user, sslmode, protocol version).","Verify the frontend/query engine service is healthy and reachable from pgwire.","Capture server-side logs at session start time to see the original error before wrapping."],"exampleFix":"// before: unwrapping loses the cause\nlet _ = session.startup(params).unwrap();\n// after: downcast to PsqlError and inspect the source\nmatch result {\n    Err(e) => { let src = e.source().map(|s| s.to_string()); log::error!(\"startup failed: {e}, source: {src:?}\"); }\n    Ok(s) => s.run().await,\n}","handlingStrategy":"try-catch","validationCode":"// validate startup params before connecting\nif database.is_empty() || user.is_empty() { return Err(\"database and user are required\"); }\nlet reachable = tokio::net::TcpStream::connect(addr).await.is_ok();","typeGuard":"fn is_startup_error(e: &PsqlError) -> bool { matches!(e, PsqlError::StartupError(_)) }","tryCatchPattern":"match conn.start().await {\n    Err(e @ PsqlError::StartupError(src)) => { log::error!(\"startup: {e} (source: {src})\"); retry_with_fixed_params(); }\n    other => other,\n}","preventionTips":["Validate user/database/sslmode connection parameters before opening a session.","Keep client PostgreSQL protocol versions within the supported range.","Monitor frontend service health; startup failures often follow frontend outages."],"tags":["pgwire","postgres-protocol","session-startup"],"backgroundTag":"connection-refused","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}