connection pool local size must be between 1 and 32

Error message

connection pool local size must be between 1 and 32

What it means

The `advanced.connection.pool.local.size` value read from the Java driver HOCON config must be between 1 and 32 inclusive. applyJavaDriverHOCON (config_file.go:111) rejects values outside that range because the Go driver caps per-host connections to a sane maximum (32) and requires at least one connection. The error aborts config-file application.

Source

Thrown at agents/drivers/cassandra-go/config_file.go:111

			return err
		}
		config.loadBalancingPolicy = policy
	}
	if value, ok, err := hoconString(parsed, javaDriverConfigPrefix+"basic.cloud.secure-connect-bundle"); err != nil {
		return err
	} else if ok {
		config.secureConnectBundle = value
	}
	if value, ok, err := hoconDuration(parsed, javaDriverConfigPrefix+"advanced.connection.connect-timeout"); err != nil {
		return err
	} else if ok {
		config.connectTimeout = value
	}
	if value, ok, err := hoconInt(parsed, javaDriverConfigPrefix+"advanced.connection.pool.local.size"); err != nil {
		return err
	} else if ok {
		if value < 1 || value > 32 {
			return fmt.Errorf("connection pool local size must be between 1 and 32")
		}
		config.numConnections = value
	}
	if value, ok, err := hoconBool(parsed, javaDriverConfigPrefix+"advanced.socket.tcp-no-delay"); err != nil {
		return err
	} else if ok {
		config.tcpNoDelay = value
	}
	if value, ok, err := hoconBool(parsed, javaDriverConfigPrefix+"advanced.socket.keep-alive"); err != nil {
		return err
	} else if ok {
		config.keepAlive = value
	}
	if value, ok, err := hoconProtocolVersion(parsed, javaDriverConfigPrefix+"advanced.protocol.version"); err != nil {
		return err
	} else if ok {
		config.protocolVersion = value
	}

View on GitHub (pinned to c0390bff16)

Solutions

Set `advanced.connection.pool.local.size` to an integer between 1 and 32 in the HOCON config file.
If you need more total connections, increase the number of hosts/IO threads instead of the per-host pool size beyond 32.
Remove the key to use the driver default (1) if custom pooling is not required.
Split oversized values across application instances rather than a single client's connection pool.

Example fix

// before (application.conf)
datastax-java-driver {
  advanced.connection.pool.local.size = 64
}
// after
datastax-java-driver {
  advanced.connection.pool.local.size = 8
}

Defensive patterns

Strategy: validation

Validate before calling

func validatePoolSize(cfg *hocon.Config) error {
    const key = "datastax-java-driver.advanced.connection.pool.local.size"
    if cfg.Get(key) == nil {
        return nil
    }
    v, err := cfg.GetIntE(key)
    if err != nil {
        return err
    }
    if v < 1 || v > 32 {
        return fmt.Errorf("%s must be in [1,32], got %d", key, v)
    }
    return nil
}

Type guard

func isValidPoolSize(v int) bool { return v >= 1 && v <= 32 }

Try / catch

if err := applyCassandraConfigFile(cfgPath); err != nil {
    if strings.Contains(err.Error(), "connection pool local size") {
        log.Fatalf("config %s: pool.local.size must be between 1 and 32", cfgPath)
    }
    return err
}

Prevention

Clamp pool sizes in config generation: min(max(v,1),32) before writing the file.
Remember per-host caps; scale horizontally instead of raising the pool beyond 32.
Keep distinct tuned configs per fleet; don't copy JVM pool numbers into shared configs blindly.

When it happens

Trigger: A HOCON file sets `datastax-java-driver.advanced.connection.pool.local.size` to 0, a negative number, or anything greater than 32; applyCassandraConfigFile triggers applyJavaDriverHOCON which validates via `value < 1 || value > 32`.

Common situations: Tuning pool size for high throughput and setting 64 or 100 copied from a JVM recommendation; a leftover 0 from a disabled template; confusion between local size and remote size limits.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/d84d7378f008b316. Report an issue: GitHub.