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.

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)

Solutions

1. Set explicit non-null values for quarkus.flyway.locations, e.g. classpath:db/migration
2. Check for config placeholders/expressions that resolve to null and fix or remove them
3. 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

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

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

• The configuration ${clazz} is missing the @ConfigRoot annota
• Unsupported value: ${value}
• Starting with Quarkus 3.25, legacy config classes (deprecate
• Invalid configuration value set for 'quarkus.arc.remove-unus
• quarkus.datasource.url and quarkus.datasource.driver have be

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