{"record":{"id":"cee5865a78505380","repo":"alibaba/spring-ai-alibaba","slug":"runtimeexception-wrapping-sqlexception-from-postgr","errorCode":null,"errorMessage":"RuntimeException wrapping SQLException from PostgresSaver construction (no literal message)","messagePattern":"RuntimeException wrapping SQLException from PostgresSaver construction \\(no literal message\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java","lineNumber":756,"sourceCode":"\t\t\t// If datasource is already set (e.g., for testing), use it directly\n\t\t\tif (datasource == null) {\n\t\t\t\tif (port == null || port <= 0) {\n\t\t\t\t\tthrow new IllegalArgumentException(\"port must be greater than 0\");\n\t\t\t\t}\n\t\t\t\tvar ds = new PGSimpleDataSource();\n\t\t\t\tds.setDatabaseName(requireNotBlank(database, \"database\"));\n\t\t\t\tds.setUser(requireNotBlank(user, \"user\"));\n\t\t\t\tds.setPassword(requireNonNull(password, \"password cannot be null\"));\n\t\t\t\tds.setPortNumbers(new int[] {port});\n\t\t\t\tds.setServerNames(new String[] {requireNotBlank(host, \"host\")});\n\t\t\t\tdatasource = ds;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\treturn new PostgresSaver(this);\n\t\t\t}\n\t\t\tcatch (SQLException e) {\n\t\t\t\tthrow new RuntimeException(e);\n\t\t\t}\n\t\t}\n\t}\n}\n","sourceCodeStart":738,"sourceCodeEnd":761,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java#L738-L761","documentation":"PostgresSaver.Builder.build() invokes the PostgresSaver constructor, which can throw SQLException (e.g. it initializes schema or validates connectivity). build() wraps that checked exception in an unchecked RuntimeException with no message, so the actual cause is in getCause().","triggerScenarios":"Calling build() when the constructor's JDBC work fails: wrong host/port, database doesn't exist, bad credentials, network unreachable, or schema initialization SQL failing.","commonSituations":"Postgres not started / wrong host in dev; wrong password after rotation; database name typo; firewall blocking the port; first-run schema migration failure.","solutions":["Inspect e.getCause() (the SQLException) for SQLState and server message to find the real problem.","Verify host, port, database, user and password by connecting with psql or another client first.","Ensure Postgres is reachable from the app (network, Docker networking, firewall).","If the cause indicates schema issues, run/check the checkpoint schema initialization manually."],"exampleFix":"// before\nvar saver = PostgresSaver.builder()...build(); // opaque RuntimeException\n// after\nPostgresSaver saver;\ntry {\n    saver = PostgresSaver.builder()...build();\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof SQLException sqlEx) {\n        throw new IllegalStateException(\"Saver init failed: \" + sqlEx.getMessage(), sqlEx);\n    }\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight: confirm DB reachable before build()\nPGSimpleDataSource probe = new PGSimpleDataSource();\nprobe.setURL(\"jdbc:postgresql://host:port/db\");\nprobe.getConnection().close();","typeGuard":null,"tryCatchPattern":"try { saver = builder.build(); } catch (RuntimeException e) { throw new IllegalStateException(\"PostgresSaver init failed: \" + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e); }","preventionTips":["Verify Postgres connectivity before building","Unwrap getCause() for the real SQLException","Validate credentials and database existence","Run schema initialization before app start"],"tags":["postgresql","initialization","jdbc","builder"],"backgroundTag":"database-query-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}