What causes "Pool size must be at least 1" in karatelabs/karate?

Pass an explicit pool size >= 1 (commonly the expected parallelism)

karatelabs/karate · error · IllegalArgumentException

Pool size must be at least 1

Error message

Pool size must be at least 1

What it means

The PooledDriverProvider constructor validates its pool size; a value below 1 cannot hold even one driver and would make the pool unusable, so it throws IllegalArgumentException immediately at construction time.

Solutions

Pass an explicit pool size >= 1 (commonly the expected parallelism)
Fix the config source so the pool-size property resolves to a positive integer
Clamp computed sizes: Math.max(1, computedSize)

Example fix

// before
int size = Integer.parseInt(cfg.get("pool-size")); // "" -> NumberFormatException/0
new PooledDriverProvider(size);
// after
int size = Math.max(1, Integer.parseInt(cfg.getOrDefault("pool-size", "4")));
new PooledDriverProvider(size);

Defensive patterns

Strategy: validation

Validate before calling

int size = Integer.parseInt(System.getProperty("karate.driver.pool-size", "4"));
if (size < 1) throw new IllegalArgumentException("pool size must be >= 1, got " + size);
PooledDriverProvider pool = new PooledDriverProvider(size);

Try / catch

try {
    pool = new PooledDriverProvider(configuredSize);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Pool size")) {
        pool = new PooledDriverProvider(Math.max(1, configuredSize));
    } else { throw e; }
}

Prevention

Clamp computed sizes with Math.max(1, n)
Validate pool-size config at startup
Never derive pool size from possibly-empty collections without a default

When it happens

Trigger: Constructing new PooledDriverProvider(0) or with a negative value, e.g. from a misconfigured karate.driver.pool-size property parsed as 0, or code computing the size from an empty config/count.

Common situations: Typo'd or missing config keys defaulting to 0, integer parsing of blank settings, programmatic pool setup with a size derived from data (e.g. number of scenarios) that was empty.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/a623d617aea43012. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/PooledDriverProvider.java:93

    private volatile boolean shutdown = false;

    /**
     * Create a pooled driver provider with auto-detected pool size.
     * Pool size will match the Suite's parallelism (threadCount).
     */
    public PooledDriverProvider() {
        // Pool size auto-detected on first acquire()
    }

    /**
     * Create a pooled driver provider with explicit pool size.
     * Use this when you need to override the auto-detected size.
     *
     * @param poolSize maximum number of drivers to create
     */
    public PooledDriverProvider(int poolSize) {
        if (poolSize < 1) {
            throw new IllegalArgumentException("Pool size must be at least 1");
        }
        this.poolSize = poolSize;
        this.availableDrivers = new ArrayBlockingQueue<>(poolSize);
    }

    @Override
    public Driver acquire(ScenarioRuntime runtime, Map<String, Object> config) {
        if (shutdown) {
            throw new IllegalStateException("Provider has been shut down");
        }

        // Initialize pool lazily with auto-detected size
        ensurePoolInitialized(runtime);

        // Check if this scenario already has a driver assigned (shouldn't happen normally)
        Driver existing = assignedDrivers.get(runtime);
        if (existing != null && !existing.isTerminated()) {
            logger.debug("Returning existing driver for scenario: {}", runtime.getScenario().getName());

View on GitHub (pinned to a22eb90246)