Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Boot cannot use the PostgreSQL JDBC URL it was given

ErrorDriver 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.

  • Applies to Spring Boot 3.5, PostgreSQL JDBC driver 42.7, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/
  2. 2Match what you see, then jump to its fix

    1. 1The error shows ${DB_ADDR_ALIAS} or similar inside the URL.The placeholder was never resolvedFix
    2. 2The 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. 3The 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

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_NAME

2Fix

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:run

Confirmed by docs.spring.io

Did this fix it?

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=Dockerfile

2Fix

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/appdb

3Verify

Restart and confirm the app connects.

./mvnw spring-boot:run

Confirmed by docs.spring.io

Did this fix it?

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=true

3Verify

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.