Spring Boot stops at startup with flywayInitializer failing
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer'Short answer
flywayInitializer is the bean that runs your migrations at startup, so any migration problem surfaces as its BeanCreationException. The real reason is in the Caused by line at the bottom of the trace. Look there first: it is usually a missing database module, a wrong database URL, a failed validation, or a non-empty schema.
Fix it fast
1Find out which cause you have
Print only the Caused by lines. The last one is the cause; ignore the long wrapper.
./mvnw spring-boot:run 2>&1 | grep -n "Caused by"2Match what you see, then jump to its fix
- 1
Caused by mentions an unsupported database, while the JDBC driver is presentThe database module for Flyway is missingFix - 2
Caused by is a connection failure, often in Docker or tests, while the app's own config looks rightFlyway uses a different datasource than you thinkFix - 3
Caused by says validation failed, or a migration checksum mismatchValidation fails because an applied migration changedFix - 4
Flyway refuses to migrate an existing, non-empty schemaThe database already has tables but no Flyway historyFix
- 1
What does the error look like?
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer'Caused by: org.flywaydb.core.api.FlywayException
Cause 1 of 4
The database module for Flyway is missing
1Check
Spring Boot's guide says that besides the starter, other databases need a vendor module. PostgreSQL needs flyway-database-postgresql and MySQL needs flyway-mysql.
./mvnw dependency:tree | grep -i flyway2Fix
Add the module that matches your database.
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>3Verify
The application starts and Flyway logs the migrations it applied.
./mvnw spring-boot:runConfirmed by docs.spring.io
Cause 2 of 4
Flyway uses a different datasource than you think
1Check
Flyway uses the primary DataSource. If spring.flyway.url, user or password are set they win; any that are unset fall back to spring.datasource values.
grep -rn "spring.flyway\|spring.datasource" src/main/resources src/test/resources2Fix
Make the URL, user and password point at the database that is actually reachable from where the app runs. In a container, use the service name, not localhost.
spring.flyway.url=jdbc:postgresql://db:5432/app
spring.flyway.user=app
spring.flyway.password=${DB_PASSWORD}3Verify
Connect to the same URL from the app's container.
psql "postgresql://app@db:5432/app" -c "SELECT 1"Confirmed by docs.spring.io
Cause 3 of 4
Validation fails because an applied migration changed
1Check
validate fails when names, types or checksums differ from what is recorded, when applied versions are no longer found locally, or when versions found locally are not applied.
./mvnw flyway:info2Fix
Restore the original file if it was edited. If the history table must be realigned, run repair with the same locations as migrate; it also removes failed entries, and leftovers from a failed migration must be cleaned by hand.
./mvnw flyway:repair3Verify
flyway:info shows no mismatch, then the app starts.
./mvnw flyway:infoConfirmed by documentation.red-gate.com
Cause 4 of 4
The database already has tables but no Flyway history
1Check
With baselineOnMigrate off (the default), Flyway will not adopt a non-empty schema that has no history table.
SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';2Fix
Set a baseline version that matches the schema's current state; only migrations above it will run. Turning it on removes a safety net, so use it once and point it only at the right database.
spring.flyway.baseline-on-migrate=true
spring.flyway.baseline-version=13Verify
Start the app; the history table gets a baseline row, then newer migrations apply.
SELECT version, description FROM flyway_schema_history;Confirmed by documentation.red-gate.com
How do I stop it coming back?
- Never edit a migration that has been applied; add a new versioned file instead.
- Name files V<VERSION>__<NAME>.sql and keep them in the configured location (default classpath:db/migration).
- In tests, use a container and a URL taken from it, so the app and Flyway see the same database.
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 cannot use the PostgreSQL JDBC URL it was given
java.lang.RuntimeException: Driver org.postgresql.Driver claims to not accept jdbcUrl
The message means the URL string handed to the driver is not a PostgreSQL JDBC URL.
3 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