quarkusio/quarkus · error · IllegalArgumentException

Datasource <dataSourceName> does not have a JDBC URL and sho

Error message

Datasource <dataSourceName> does not have a JDBC URL and should not be created

What it means

Agroal (Quarkus datasources) refuses to create a datasource when no JDBC URL is configured for it. The check exists because a datasource without a connection URL has nothing to connect to; typically the user enabled JDBC (e.g. set a db-kind or driver) but forgot quarkus.datasource.jdbc.url.

Source

Thrown at extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSources.java:156

    public AgroalDataSource getDataSource(String dataSourceName) {
        return ClientProxy.unwrap(AgroalDataSourceUtil.dataSourceInstance(dataSourceName).get());
    }

    @SuppressWarnings("resource")
    public AgroalDataSource createDataSource(String dataSourceName, boolean otelEnabled,
            Map<String, String> buildTimeJdbcProperties) {
        if (!agroalDataSourceSupport.entries.containsKey(dataSourceName)) {
            throw new IllegalArgumentException("No datasource named '" + dataSourceName + "' exists");
        }

        DataSourceJdbcBuildTimeConfig dataSourceJdbcBuildTimeConfig = dataSourcesJdbcBuildTimeConfig
                .dataSources().get(dataSourceName).jdbc();
        DataSourceRuntimeConfig dataSourceRuntimeConfig = dataSourcesRuntimeConfig.dataSources().get(dataSourceName);

        DataSourceJdbcRuntimeConfig dataSourceJdbcRuntimeConfig = dataSourcesJdbcRuntimeConfig
                .dataSources().get(dataSourceName).jdbc();
        if (!dataSourceJdbcRuntimeConfig.url().isPresent()) {
            throw new IllegalArgumentException(
                    "Datasource " + dataSourceName + " does not have a JDBC URL and should not be created");
        }

        // we first make sure that all available JDBC drivers are loaded in the current TCCL
        loadDriversInTCCL();

        AgroalDataSourceSupport.Entry matchingSupportEntry = agroalDataSourceSupport.entries.get(dataSourceName);
        String resolvedDriverClass = matchingSupportEntry.resolvedDriverClass;
        Class<?> driver;
        try {
            driver = Class.forName(resolvedDriverClass, true, Thread.currentThread().getContextClassLoader());
        } catch (ClassNotFoundException e) {
            throw new RuntimeException(
                    "Unable to load the datasource driver " + resolvedDriverClass + " for datasource " + dataSourceName, e);
        }

        String jdbcUrl = dataSourceJdbcRuntimeConfig.url().get();

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.datasource.<name>.jdbc.url (e.g. jdbc:postgresql://localhost:5432/mydb) in application.properties or via env var QUARKUS_DATASOURCE_<NAME>_JDBC_URL
If the datasource should not exist, remove all its jdbc.* config so it is not created at all
Verify the property key spelling matches the datasource name exactly (unnamed default datasource uses quarkus.datasource.jdbc.url)
In prod, confirm config sources (env vars, -D flags) actually supply the URL since dev services do not apply

Example fix

// before
quarkus.datasource.orders.db-kind=postgresql
// after
quarkus.datasource.orders.db-kind=postgresql
quarkus.datasource.orders.jdbc.url=jdbc:postgresql://localhost:5432/orders
quarkus.datasource.orders.jdbc.driver=org.postgresql.Driver

Defensive patterns

Strategy: validation

Validate before calling

String url = ConfigProvider.getConfig().getValue("quarkus.datasource.orders.jdbc.url", String.class); // throws NoSuchElementException if absent — set it before startup

Prevention

Always pair db-kind with jdbc.url for every named datasource
Use Quarkus config mapping checks or a startup smoke test that pings each datasource
Keep prod URLs in env vars and verify them in CI before packaging
Remember dev services supply URLs only in dev mode

When it happens

Trigger: Calling DataSources.createDataSource (via config apply/startup) for a named datasource whose dataSourcesJdbcRuntimeConfig.dataSources().get(name).jdbc().url() is empty.

Common situations: Defining a second named datasource and setting quarkus.datasource.<name>.db-kind but not quarkus.datasource.<name>.jdbc.url; relying on dev services in dev mode then running prod without a URL; typo in the property name.

Related errors

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