Spring Boot cannot use the PostgreSQL JDBC URL it was given
Driver org.postgresql.Driver claims to not accept jdbcUrl, jdbc:postgresql://${DB_ADDR_ALIAS}:${DB_PORT}/${DB_NAME}Short answer
The message means the URL string handed to the driver is not a PostgreSQL JDBC URL. Most often a placeholder such as ${DB_HOST} was never replaced and arrived as literal text. Check the final URL, supply the variables or defaults, and keep the form jdbc:postgresql://host:port/database with reserved characters percent-encoded.
Fix it fast
1Find out which cause you have
Read the URL in the error message. If it still contains ${...}, nothing replaced the placeholder. If it is plain text, check its shape against the documented form.
printenv | grep -E "DB_ADDR_ALIAS|DB_PORT|DB_NAME" grep -rn "datasource" src/main/resources/2Match what you see, then jump to its fix
- 1
The error shows ${DB_ADDR_ALIAS} or similar inside the URL.The placeholder was never resolvedFix - 2
The placeholder sits in a file other than application.properties or application.yaml, such as a plain XML, Maven or Docker file.The URL is built outside Spring's property handlingFix - 3
The URL is fully resolved but missing the jdbc:postgresql:// prefix, or has a space or special character in it.The URL does not follow the PostgreSQL JDBC formFix
- 1
What does the error look like?
Driver org.postgresql.Driver claims to not accept jdbcUrl, jdbc:postgresql://${DB_ADDR_ALIAS}:${DB_PORT}/${DB_NAME}java.lang.RuntimeException: Driver org.postgresql.Driver claims to not accept jdbcUrl
Cause 1 of 3
The placeholder was never resolved
1Check
Spring fills ${name} from its Environment, which includes system properties and environment variables. If the variable is missing where the app runs (container, IDE run configuration, systemd unit), the text stays as it is.
printenv DB_ADDR_ALIAS DB_PORT DB_NAME2Fix
Export the variables in the process that starts the app, or give each placeholder a default with a colon so the app starts with a sensible value.
# application.properties
spring.datasource.url=jdbc:postgresql://${DB_ADDR_ALIAS:localhost}:${DB_PORT:5432}/${DB_NAME:appdb}3Verify
Start the app and look for a successful pool start.
./mvnw spring-boot:runConfirmed by docs.spring.io
Cause 2 of 3
The URL is built outside Spring's property handling
1Check
Placeholders in application.properties and application.yaml are filtered through the Environment when used. Do not expect the same filtering in other files. Environment variables also map by name, so DB_PORT is not the same as a property named db.port.
grep -rn "DB_ADDR_ALIAS" . --include=*.xml --include=*.properties --include=*.yml --include=*.yaml --include=Dockerfile2Fix
Move the URL into application.properties or application.yaml, or set the whole property from the environment with the matching name.
export SPRING_DATASOURCE_URL=jdbc:postgresql://db.example.com:5432/appdb3Verify
Restart and confirm the app connects.
./mvnw spring-boot:runConfirmed by docs.spring.io
Cause 3 of 3
The URL does not follow the PostgreSQL JDBC form
1Check
The documented forms are jdbc:postgresql://host:port/database and jdbc:postgresql://host/database. Reserved characters such as / : @ & # = ? and space inside any part of the URL must be percent-encoded.
echo "$SPRING_DATASOURCE_URL"2Fix
Use the documented shape. Host defaults to localhost and port to 5432. Percent-encode special characters in any part, passwords included.
spring.datasource.url=jdbc:postgresql://db.example.com:5432/appdb?ssl=true3Verify
The URL starts with jdbc:postgresql:// and has no unencoded reserved characters.
echo "$SPRING_DATASOURCE_URL" | grep -E '^jdbc:postgresql://'Confirmed by jdbc.postgresql.org
How do I stop it coming back?
- Give every placeholder in a datasource URL a default, or fail the deploy when a variable is missing.
- Log the resolved URL (without the password) at startup in non-production.
- Keep one source of truth for the URL: properties file or environment, not both.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Databases
H2 in PostgreSQL mode still behaves differently from PostgreSQL
Names or null ordering differ from PostgreSQL in test results
H2 compatibility modes are switched on in the JDBC URL and cover only a small part of the differences between databases.
4 causes, each with a fixDatabases
Hibernate insert fails: column is of type bit but expression is of type boolean
ERROR: column "active" is of type bit but expression is of type boolean
PostgreSQL has a real boolean type and a separate bit type, and it will not convert one to the other on insert.
3 causes, each with a fixDatabases
Spring Boot cannot configure a DataSource for PostgreSQL
Failed to determine a suitable driver class
Spring Boot builds a pooled DataSource only when it has a JDBC URL and a loadable driver.
3 causes, each with a fixDatabases
Spring Boot stops at startup with flywayInitializer failing
Caused by: org.flywaydb.core.api.FlywayException
flywayInitializer is the bean that runs your migrations at startup, so any migration problem surfaces as its BeanCreationException.
4 causes, each with a fixDatabases
Spring Boot JPA cannot find the PostgreSQL table it maps to
ERROR: relation "telephone_number" does not exist
Spring Boot maps an entity to a lowercase snake_case table name and creates tables on its own only for embedded databases.
2 causes, each with a fixDatabases
Flyway cannot handle the PostgreSQL URL after upgrading to Flyway 10 or newer
No database found to handle jdbc:postgresql://localhost:5432/app
Since Flyway 10, each database has its own module.
4 causes, each with a fix