alibaba/druid · error · IllegalArgumentException

timeBetweenLogStatsMillis not support useGlobalDataSourceSta

Error message

timeBetweenLogStatsMillis not support useGlobalDataSourceStat=true

What it means

IllegalArgumentException thrown during init() when both timeBetweenLogStatsMillis > 0 and useGlobalDataSourceStat=true are set. The stat-logging task (which dumps pool stats periodically) relies on per-datasource stat objects and cannot operate against the shared global stat store, so the combination is forbidden.

Source

Thrown at core/src/main/java/com/alibaba/druid/pool/DruidDataSource.java:731

                if (cacheServerConfigurationSet) {
                    this.connectProperties.put("cacheServerConfiguration", "true");
                }
            }

            if (maxActive <= 0) {
                throw new IllegalArgumentException("illegal maxActive " + maxActive);
            }

            if (maxActive < minIdle) {
                throw new IllegalArgumentException("illegal maxActive " + maxActive);
            }

            if (getInitialSize() > maxActive) {
                throw new IllegalArgumentException("illegal initialSize " + this.initialSize + ", maxActive " + maxActive);
            }

            if (timeBetweenLogStatsMillis > 0 && useGlobalDataSourceStat) {
                throw new IllegalArgumentException("timeBetweenLogStatsMillis not support useGlobalDataSourceStat=true");
            }

            if (maxEvictableIdleTimeMillis < minEvictableIdleTimeMillis) {
                throw new SQLException("maxEvictableIdleTimeMillis must be grater than minEvictableIdleTimeMillis");
            }

            if (keepAlive && keepAliveBetweenTimeMillis <= timeBetweenEvictionRunsMillis) {
                throw new SQLException("keepAliveBetweenTimeMillis must be greater than timeBetweenEvictionRunsMillis");
            }

            if (this.driverClass != null) {
                this.driverClass = driverClass.trim();
            }

            initFromSPIServiceLoader();

            resolveDriver();

View on GitHub (pinned to fa8dc99126)

Solutions

If you want periodic stat logging, set useGlobalDataSourceStat=false (default) and keep timeBetweenLogStatsMillis.
If you need global stats, remove/unset timeBetweenLogStatsMillis and export stats another way.
Pick one: per-datasource stat logging OR global stat aggregation, not both.

Example fix

// before
dataSource.setUseGlobalDataSourceStat(true);
dataSource.setTimeBetweenLogStatsMillis(60_000); // throws at init
// after
dataSource.setUseGlobalDataSourceStat(false);
dataSource.setTimeBetweenLogStatsMillis(60_000);

Defensive patterns

Strategy: validation

Validate before calling

if (dataSource.isUseGlobalDataSourceStat() && dataSource.getTimeBetweenLogStatsMillis() > 0) {
    throw new IllegalStateException("pick one: timeBetweenLogStatsMillis OR useGlobalDataSourceStat, not both");
}

Prevention

Decide monitoring strategy up front: per-pool stat logging or global aggregation.
Avoid template configs that enable both flags.
Document the chosen metrics export path in your runbook.

When it happens

Trigger: init() with timeBetweenLogStatsMillis configured to a positive value AND useGlobalDataSourceStat enabled. The check at line 730 throws.

Common situations: Turning on global stat aggregation while also enabling periodic stat logging; carrying both flags over from a template config; metrics integrations that set useGlobalDataSourceStat plus a stats logger.

Related errors

AI-assisted analysis of alibaba/druid@fa8dc99126 (2026-08-14). Data as JSON: /api/errors/cfde1c51a42a40b6. Report an issue: GitHub.