quarkusio/quarkus · error · ConfigurationException

Username and password must be defined when a JDBC URL is pro

Error message

Username and password must be defined when a JDBC URL is provided in the Flyway configuration

What it means

When Flyway is configured with an explicit JDBC URL, Quarkus creates a dedicated DataSource for Flyway, which requires both username and password. If only the URL (or the URL plus only one credential) is present, a ConfigurationException is thrown.

Source

Thrown at extensions/flyway/runtime/src/main/java/io/quarkus/flyway/runtime/FlywayCreator.java:60

        this.flywayRuntimeConfig = flywayRuntimeConfig;
        this.flywayBuildTimeConfig = flywayBuildTimeConfig;
        this.customizers = customizers;
    }

    public FlywayCreator withCallbacks(Collection<Callback> callbacks) {
        this.callbacks = callbacks;
        return this;
    }

    public Flyway createFlyway(DataSource dataSource) {
        FluentConfiguration configure = Flyway.configure();

        if (flywayRuntimeConfig.jdbcUrl().isPresent()) {
            if (flywayRuntimeConfig.username().isPresent() && flywayRuntimeConfig.password().isPresent()) {
                configure.dataSource(flywayRuntimeConfig.jdbcUrl().get(), flywayRuntimeConfig.username().get(),
                        flywayRuntimeConfig.password().get());
            } else {
                throw new ConfigurationException(
                        "Username and password must be defined when a JDBC URL is provided in the Flyway configuration");
            }
        } else {
            if (flywayRuntimeConfig.username().isPresent() && flywayRuntimeConfig.password().isPresent()) {
                AgroalDataSource agroalDataSource = (AgroalDataSource) dataSource;
                String jdbcUrl = agroalDataSource.getConfiguration().connectionPoolConfiguration()
                        .connectionFactoryConfiguration().jdbcUrl();

                configure.dataSource(jdbcUrl, flywayRuntimeConfig.username().get(),
                        flywayRuntimeConfig.password().get());
            } else if (dataSource != null) {
                configure.dataSource(dataSource);
            }
        }
        if (flywayRuntimeConfig.initSql().isPresent()) {
            configure.initSql(flywayRuntimeConfig.initSql().get());
        }
        if (flywayRuntimeConfig.connectRetries().isPresent()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Set both quarkus.flyway.username and quarkus.flyway.password alongside quarkus.flyway.jdbc-url
2. Remove quarkus.flyway.jdbc-url to let Flyway reuse the default Quarkus datasource credentials instead
3. Verify the environment variables referenced by the properties are actually present in the deployment environment

Example fix

// before
quarkus.flyway.jdbc-url=jdbc:postgresql://db:5432/mydb
// after
quarkus.flyway.jdbc-url=jdbc:postgresql://db:5432/mydb
quarkus.flyway.username=flyway
quarkus.flyway.password=${FLYWAY_PASSWORD}

if (jdbcUrl != null && (username == null || password == null)) {
    throw new IllegalArgumentException("quarkus.flyway.jdbc-url requires both username and password");
}

try {
    flyway.migrate();
} catch (ConfigurationException e) {
    log.error("Flyway JDBC credentials missing: " + e.getMessage());
    throw e;
}

When it happens

Trigger: quarkus.flyway.jdbc-url is set but quarkus.flyway.username and quarkus.flyway.password are not both set (or only one of them is).

Common situations: Pointing Flyway at a database different from the default Agroal datasource; password supplied only via env var that is absent; assuming Flyway inherits the datasource credentials when jdbc-url is set.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Flyway migration location may not be null.
• Datasource must be defined for persistence unit '%s'. Settin
• Username '%s' not in the 'test_user' table
• Failed to load application configuration
• Failed to initialize application configuration

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/575c7aa34c3fd4fa. Report an issue: GitHub.