questdb/questdb · error · ServerConfigurationException

TCP ILP buffer size is too small, should be at least ${MIN_T

Error message

TCP ILP buffer size is too small, should be at least ${MIN_TCP_ILP_BUF_SIZE}, [${PropertyKey.LINE_TCP_RECV_BUFFER_SIZE.propertyPath}=${lineTcpRecvBufferSize}]

What it means

Validates the TCP ILP (InfluxDB Line Protocol over TCP) receive buffer: line.tcp.recv.buffer.size (falling back to deprecated line.tcp.msg.buffer.size, default 131072) must be at least MIN_TCP_ILP_BUF_SIZE, which is AuthUtils.CHALLENGE_LEN + 1 = 513 bytes. The floor exists because the initial ILP/TCP handshake writes an auth challenge that must fit in the first receive buffer regardless of user sizing.

Source

Thrown at core/src/main/java/io/questdb/PropServerConfiguration.java:2112

                this.lineTcpConnectionPoolInitialCapacity = getInt(properties, env, PropertyKey.LINE_TCP_CONNECTION_POOL_CAPACITY, 8);

                // deprecated
                this.lineTcpNetConnectionRcvBuf = getIntSize(properties, env, PropertyKey.LINE_TCP_NET_RECV_BUF_SIZE, -1);
                this.lineTcpNetConnectionRcvBuf = getIntSize(properties, env, PropertyKey.LINE_TCP_NET_CONNECTION_RCVBUF, lineTcpNetConnectionRcvBuf);
                // deprecated
                this.lineTcpRecvBufferSize = getIntSize(properties, env, PropertyKey.LINE_TCP_MSG_BUFFER_SIZE, 131072);
                this.lineTcpRecvBufferSize = getIntSize(properties, env, PropertyKey.LINE_TCP_RECV_BUFFER_SIZE, lineTcpRecvBufferSize);
                this.lineTcpMaxMeasurementSize = getIntSize(properties, env, PropertyKey.LINE_TCP_MAX_MEASUREMENT_SIZE, 32768);
                if (lineTcpMaxMeasurementSize > lineTcpRecvBufferSize) {
                    lineTcpRecvBufferSize = lineTcpMaxMeasurementSize;
                }
                this.lineTcpMaxRecvBufferSize = getLongSize(properties, env, PropertyKey.LINE_TCP_MAX_RECV_BUFFER_SIZE, Numbers.SIZE_1GB);
                if (lineTcpRecvBufferSize > lineTcpMaxRecvBufferSize) {
                    lineTcpMaxRecvBufferSize = lineTcpRecvBufferSize;
                }
                if (lineTcpRecvBufferSize < MIN_TCP_ILP_BUF_SIZE) {
                    throw new ServerConfigurationException(
                            "TCP ILP buffer size is too small, should be at least " + MIN_TCP_ILP_BUF_SIZE + ", ["
                                    + PropertyKey.LINE_TCP_RECV_BUFFER_SIZE.getPropertyPath() + "=" + lineTcpRecvBufferSize + ']');
                }

                this.lineTcpWriterQueueCapacity = getQueueCapacity(properties, env, PropertyKey.LINE_TCP_WRITER_QUEUE_CAPACITY, 128);
                this.lineTcpWriterWorkerCount = getInt(properties, env, PropertyKey.LINE_TCP_WRITER_WORKER_COUNT, 0); // Use shared write pool by default
                this.lineTcpWriterWorkerAffinity = getAffinity(properties, env, PropertyKey.LINE_TCP_WRITER_WORKER_AFFINITY, lineTcpWriterWorkerCount);
                this.lineTcpWriterWorkerPoolHaltOnError = getBoolean(properties, env, PropertyKey.LINE_TCP_WRITER_HALT_ON_ERROR, false);
                this.lineTcpWriterWorkerYieldThreshold = getLong(properties, env, PropertyKey.LINE_TCP_WRITER_WORKER_YIELD_THRESHOLD, 10);
                this.lineTcpWriterWorkerNapThreshold = getLong(properties, env, PropertyKey.LINE_TCP_WRITER_WORKER_NAP_THRESHOLD, 7_000);
                this.lineTcpWriterWorkerSleepThreshold = getLong(properties, env, PropertyKey.LINE_TCP_WRITER_WORKER_SLEEP_THRESHOLD, 10_000);
                this.symbolCacheWaitBeforeReload = getMicros(properties, env, PropertyKey.LINE_TCP_SYMBOL_CACHE_WAIT_BEFORE_RELOAD, 500_000);
                this.lineTcpIOWorkerCount = getInt(properties, env, PropertyKey.LINE_TCP_IO_WORKER_COUNT, 0); // Use shared IO pool by default
                this.lineTcpIOWorkerAffinity = getAffinity(properties, env, PropertyKey.LINE_TCP_IO_WORKER_AFFINITY, lineTcpIOWorkerCount);
                this.lineTcpIOWorkerPoolHaltOnError = getBoolean(properties, env, PropertyKey.LINE_TCP_IO_HALT_ON_ERROR, false);
                this.lineTcpIOWorkerYieldThreshold = getLong(properties, env, PropertyKey.LINE_TCP_IO_WORKER_YIELD_THRESHOLD, 10);
                this.lineTcpIOWorkerNapThreshold = getLong(properties, env, PropertyKey.LINE_TCP_IO_WORKER_NAP_THRESHOLD, 7_000);
                this.lineTcpIOWorkerSleepThreshold = getLong(properties, env, PropertyKey.LINE_TCP_IO_WORKER_SLEEP_THRESHOLD, 10_000);

View on GitHub (pinned to 6610ab113b)

Solutions

Set line.tcp.recv.buffer.size to at least 513; realistically keep the 131072 default or size it to your largest measurement plus header
If you also lowered line.tcp.max.measurement.size, raise it above 513 or remove it
Remove the deprecated line.tcp.msg.buffer.size key so it cannot silently supply an undersized base value

Example fix

# before
line.tcp.recv.buffer.size=256
line.tcp.max.measurement.size=256

# after
line.tcp.recv.buffer.size=131072
# line.tcp.max.measurement.size removed (default 32768)

Defensive patterns

Strategy: validation

Validate before calling

int recv = parseSize(firstNonBlank(props.get("line.tcp.recv.buffer.size"), firstNonBlank(props.get("line.tcp.msg.buffer.size"), "131072")));
int maxMeas = parseSize(firstNonBlank(props.get("line.tcp.max.measurement.size"), "32768"));
int effective = Math.max(recv, maxMeas);
if (effective < 513) { // MIN_TCP_ILP_BUF_SIZE = AuthUtils.CHALLENGE_LEN + 1
    throw new IllegalStateException("TCP ILP buffer resolves to " + effective + ", below the 513-byte floor");
}

Prevention

Keep line.tcp.recv.buffer.size at the 131072 default unless measurement sizes force higher
Delete the deprecated line.tcp.msg.buffer.size key from old configs
Remember the buffer also carries the 512-byte auth challenge, so it can never go small

When it happens

Trigger: Setting line.tcp.recv.buffer.size (or the deprecated line.tcp.msg.buffer.size) below 513. Note the code first raises the buffer to line.tcp.max.measurement.size (default 32768) if the measurement size is larger, so in practice you must also set a tiny max-measurement-size (< 513) to actually land here with small values.

Common situations: Aggressive memory tuning on small containers shrinking both buffer knobs together; copying a config that was never actually booted; using the deprecated key with a small value on a version where the new key's default no longer masks it.

Related errors

AI-assisted analysis of questdb/questdb@6610ab113b (2026-08-14). Data as JSON: /api/errors/e1dc0bff02b98347. Report an issue: GitHub.