Introduction

Failed to bind properties under ... to com.zaxxer.hikari.HikariDataSource usually means Spring Boot found configuration that was intended for a data source, but could not map it cleanly into the Hikari configuration object. The actual cause is often mundane: the wrong property prefix, a misspelled key, YAML indentation, or mixing url and jdbc-url in the wrong place. The fastest fix is to stop treating it as a mysterious Hikari problem and inspect the exact property binding path.

What Spring Boot Is Trying to Bind

Spring Boot reads properties from application.properties or application.yml, matches them to a configuration prefix, and binds them into an object. For a default data source setup, that usually means keys under spring.datasource.

A minimal working example looks like this:

1spring.datasource.url=jdbc:postgresql://localhost:5432/appdb
2spring.datasource.username=appuser
3spring.datasource.password=secret
4spring.datasource.driver-class-name=org.postgresql.Driver

If you are configuring Hikari-specific settings, they usually live under the Hikari sub-prefix:

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.connection-timeout=30000

If the prefix is wrong or the keys are malformed, binding fails before the application can start cleanly.

Common Real Causes

The most common causes are:

• typo in the property name
• bad YAML indentation
• custom @ConfigurationProperties prefix that does not match the file
• missing JDBC driver dependency
• profile-specific config file not being loaded
• using Hikari property names in the wrong section

For example, this YAML looks close to correct but is broken if indentation is off:

1spring:
2  datasource:
3    url: jdbc:mysql://localhost:3306/appdb
4    username: appuser
5    password: secret
6    hikari:
7      maximum-pool-size: 10

One misplaced indent can be enough to make the binder think the values belong to a different object or no object at all.

Custom DataSource Beans Need Matching Prefixes

A very common advanced-case error happens when you define your own DataSource bean with @ConfigurationProperties and then forget that the prefix changed.

1@Bean
2@ConfigurationProperties("app.datasource")
3public DataSource dataSource() {
4    return DataSourceBuilder.create()
5        .type(com.zaxxer.hikari.HikariDataSource.class)
6        .build();
7}

If you use that bean definition, the properties must live under app.datasource, not spring.datasource:

app.datasource.url=jdbc:postgresql://localhost:5432/appdb
app.datasource.username=appuser
app.datasource.password=secret

When the prefix and the file do not match, the binder error can look like a Hikari failure even though the real problem is configuration layout.

How to Debug It Quickly

Start with the exception message and look for the property path Spring mentions. Then check:

• which config file is active
• which Spring profile is active
• which bean prefix is being used
• whether the JDBC driver dependency is on the classpath
• whether the property names are valid for the object being bound

The shortest path to a fix is often to reduce the configuration to a minimal working set, start the app, and then add pool properties back one at a time.

Common Pitfalls

• Mixing spring.datasource keys with a custom @ConfigurationProperties prefix.
• Assuming the binder is wrong when the real issue is YAML indentation.
• Using pool-specific keys under the wrong prefix.
• Forgetting that a different Spring profile may be loading a different file than the one you just edited.
• Chasing Hikari internals before confirming the datasource URL, username, password, and driver are valid.

Summary

• This error usually means Spring Boot could not map datasource properties into HikariDataSource cleanly.
• The most common causes are wrong prefixes, typos, indentation problems, and missing dependencies.
• For the default datasource, start with spring.datasource.url, username, and password.
• If you define a custom datasource bean, the property prefix in code and config must match exactly.
• Debug the binding path first; most fixes are configuration corrections, not Hikari code changes.