What causes "request.timeout.ms must be a positive integer" in t8y2/dbx?

Set request.timeout.ms to a plain positive integer of milliseconds, e.g. "30000".

t8y2/dbx · error · IllegalArgumentException

request.timeout.ms must be a positive integer

Error message

request.timeout.ms must be a positive integer

What it means

KafkaAgent reads the configured request.timeout.ms (falling back to DEFAULT_REQUEST_TIMEOUT_MS) and parses it as an integer. If the configured value is not a valid integer, it wraps the NumberFormatException in this IllegalArgumentException. This fails fast at connection setup instead of producing an opaque Kafka client error later.

Source

Thrown at agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java:1727

                "Peek message count must be between 1 and " + MAX_PEEK_MESSAGE_COUNT
            );
        }
        return count;
    }

    static int peekRequestTimeoutMs(JsonObject conn, Properties props) {
        Integer connectionTimeout = integerOrNull(conn, "request_timeout_ms");
        if (connectionTimeout != null) {
            return positiveTimeoutMs("request_timeout_ms", connectionTimeout);
        }
        String configuredTimeout = props.getProperty(
            ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG,
            String.valueOf(DEFAULT_REQUEST_TIMEOUT_MS)
        );
        try {
            return positiveTimeoutMs(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG, Integer.parseInt(configuredTimeout));
        } catch (NumberFormatException error) {
            throw new IllegalArgumentException(
                ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG + " must be a positive integer", error
            );
        }
    }

    private static int positiveTimeoutMs(String name, int timeoutMs) {
        if (timeoutMs <= 0) {
            throw new IllegalArgumentException(name + " must be a positive integer");
        }
        return timeoutMs;
    }

    static Properties peekConsumerProperties(JsonObject conn, int count) {
        Properties props = new Properties();
        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers(conn));
        applyConnectionProperties(conn, props);
        props.put(ConsumerConfig.GROUP_ID_CONFIG, "dbx-peek-" + UUID.randomUUID());
        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,

View on GitHub (pinned to c0390bff16)

Solutions

Set request.timeout.ms to a plain positive integer of milliseconds, e.g. "30000".
If the value comes from an env var or templated config, verify substitution produced digits only (no empty string or placeholder).
Remove unit suffixes/separators; the driver does not parse human-readable durations.

Example fix

// before
config.put("request.timeout.ms", "30s");

// after
config.put("request.timeout.ms", "30000");

Defensive patterns

Strategy: validation

Validate before calling

String v = config.getProperty("request.timeout.ms");
if (v == null || !v.matches("\\d+") || Integer.parseInt(v) <= 0) {
    throw new IllegalArgumentException("request.timeout.ms must be a positive integer string like 30000");
}

Try / catch

try {
    consumer = agent.connect(conn);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("request.timeout.ms")) {
        conn.put("request.timeout.ms", "30000"); // reset to default and retry
        consumer = agent.connect(conn);
    } else throw e;
}

Prevention

Store timeout config as plain millisecond integers, never with unit suffixes
Validate all numeric config values with a regex ^[0-9]+$ at load time
Check env-var substitution output for empty strings or leftover placeholders

When it happens

Trigger: Setting request.timeout.ms in the Kafka connection config to a non-integer value such as "30s", "30_000", "30,000", "", or a whitespace/full-width-digit string, then opening a connection or performing a peek.

Common situations: Config values copied from documentation that use unit suffixes (ms assumed but "5000ms" written); env-var substitution leaving a placeholder or empty string; locale-formatted numbers with separators; YAML/JSON config quoting mistakes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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