What causes "Flyway migration location may not be null." in quarkusio/quarkus?

Set explicit non-null values for quarkus.flyway.locations, e.g. classpath:db/migration

quarkusio/quarkus · error · IllegalStateException

Flyway migration location may not be null.

Error message

Flyway migration location may not be null.

What it means

Flyway migration locations are normalized at build time so they can be resolved through ClassLoader.getResources(). A null location is invalid — this defensive IllegalStateException is thrown to prevent a null classpath lookup later.

Solutions

Set explicit non-null values for quarkus.flyway.locations, e.g. classpath:db/migration
Check for config placeholders/expressions that resolve to null and fix or remove them
If locations come from code (custom processor), filter null entries before normalization

Example fix

// before
quarkus.flyway.locations=${missing.property}
// after
quarkus.flyway.locations=classpath:db/migration

Defensive patterns

Strategy: validation

Validate before calling

String loc = config.getOptionalValue("quarkus.flyway.locations", String.class).orElse("classpath:db/migration");
Objects.requireNonNull(loc, "Flyway location must not be null");

Prevention

Always set explicit quarkus.flyway.locations values
Avoid config placeholders that can resolve to null
Filter nulls before passing location lists to Flyway setup

When it happens

Trigger: quarkus.flyway.locations (or a datasource-specific locations entry) contains/resolves to a null element — typically from a misconfigured collection or an unresolvable config expression feeding normalizeLocation.

Common situations: A location list built programmatically with a null entry; config property interpolated from a missing value; custom extension or code passing null into location normalization.

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

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

Appendix: source

Thrown at extensions/flyway/deployment/src/main/java/io/quarkus/flyway/deployment/FlywayProcessor.java:375

                    .build());
            ClassPathUtils.consumeAsPaths(Thread.currentThread().getContextClassLoader(), location, path -> {
                Set<String> applicationMigrations = null;
                try {
                    applicationMigrations = FlywayProcessor.this.getApplicationMigrationsFromPath(finalLocation, path);
                } catch (IOException e) {
                    LOGGER.warnv(e,
                            "Can't process files in path %s", path);
                }
                if (applicationMigrations != null) {
                    applicationMigrationResources.addAll(applicationMigrations);
                }
            });
        }
    }

    private String normalizeLocation(String location) {
        if (location == null) {
            throw new IllegalStateException("Flyway migration location may not be null.");
        }

        // Strip any 'classpath:' protocol prefixes because they are assumed
        // but not recognized by ClassLoader.getResources()
        if (location.startsWith(CLASSPATH_APPLICATION_MIGRATIONS_PROTOCOL + ':')) {
            location = location.substring(CLASSPATH_APPLICATION_MIGRATIONS_PROTOCOL.length() + 1);
            if (location.startsWith("/")) {
                location = location.substring(1);
            }
        }
        if (!location.endsWith("/")) {
            location += "/";
        }

        return location;
    }

    private Set<String> getApplicationMigrationsFromPath(final String location, final Path rootPath)

View on GitHub (pinned to e1c734241f)