Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Boot stops at startup with flywayInitializer failing

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

  • Applies to Spring Boot 4.0, Flyway 11, PostgreSQL 17, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1Caused by mentions an unsupported database, while the JDBC driver is presentThe database module for Flyway is missingFix
    2. 2Caused 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. 3Caused by says validation failed, or a migration checksum mismatchValidation fails because an applied migration changedFix
    4. 4Flyway refuses to migrate an existing, non-empty schemaThe database already has tables but no Flyway historyFix

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 flyway

2Fix

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

Confirmed by docs.spring.io

Did this fix it?

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

2Fix

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

Did this fix it?

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

2Fix

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

3Verify

flyway:info shows no mismatch, then the app starts.

./mvnw flyway:info

Confirmed by documentation.red-gate.com

Did this fix it?

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

3Verify

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

Did this fix it?

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

Next step

Want this handled for good?

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