alibaba/spring-ai-alibaba · error · RuntimeException

RuntimeException wrapping SQLException from PostgresSaver co

Error message

RuntimeException wrapping SQLException from PostgresSaver construction (no literal message)

What it means

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().

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java:756

			// If datasource is already set (e.g., for testing), use it directly
			if (datasource == null) {
				if (port == null || port <= 0) {
					throw new IllegalArgumentException("port must be greater than 0");
				}
				var ds = new PGSimpleDataSource();
				ds.setDatabaseName(requireNotBlank(database, "database"));
				ds.setUser(requireNotBlank(user, "user"));
				ds.setPassword(requireNonNull(password, "password cannot be null"));
				ds.setPortNumbers(new int[] {port});
				ds.setServerNames(new String[] {requireNotBlank(host, "host")});
				datasource = ds;
			}

			try {
				return new PostgresSaver(this);
			}
			catch (SQLException e) {
				throw new RuntimeException(e);
			}
		}
	}
}

View on GitHub (pinned to f82da0b50f)

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.

Example fix

// before
var saver = PostgresSaver.builder()...build(); // opaque RuntimeException
// after
PostgresSaver saver;
try {
    saver = PostgresSaver.builder()...build();
} catch (RuntimeException e) {
    if (e.getCause() instanceof SQLException sqlEx) {
        throw new IllegalStateException("Saver init failed: " + sqlEx.getMessage(), sqlEx);
    }
    throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: confirm DB reachable before build()
PGSimpleDataSource probe = new PGSimpleDataSource();
probe.setURL("jdbc:postgresql://host:port/db");
probe.getConnection().close();

Try / catch

try { saver = builder.build(); } catch (RuntimeException e) { throw new IllegalStateException("PostgresSaver init failed: " + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e); }

Prevention

Verify Postgres connectivity before building
Unwrap getCause() for the real SQLException
Validate credentials and database existence
Run schema initialization before app start

When it happens

Trigger: 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.

Common situations: Postgres not started / wrong host in dev; wrong password after rotation; database name typo; firewall blocking the port; first-run schema migration failure.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/cee5865a78505380. Report an issue: GitHub.