questdb/questdb · error · ServerConfigurationException

${PropertyKey.QWP_UDP_MAX_UNCOMMITTED_DATAGRAMS.propertyPath

Error message

${PropertyKey.QWP_UDP_MAX_UNCOMMITTED_DATAGRAMS.propertyPath} must be at least 1

What it means

Validates qwp.udp.max.uncommitted.datagrams (PropertyKey.QWP_UDP_MAX_UNCOMMITTED_DATAGRAMS, default 1_048_576), the count-based commit trigger for the QWP UDP path: once this many datagrams are buffered, a commit fires. Values below 1 (0 or negative) are rejected at config load because the trigger would never arm.

Source

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

            }
            this.qwpMaxUncommittedRows = getLong(properties, env, PropertyKey.QWP_MAX_UNCOMMITTED_ROWS, QwpConstants.DEFAULT_MAX_UNCOMMITTED_ROWS);
            if (qwpMaxUncommittedRows < 1) {
                throw new ServerConfigurationException(
                        PropertyKey.QWP_MAX_UNCOMMITTED_ROWS.getPropertyPath()
                                + " must be at least 1"
                );
            }
            long qwpUdpCommitInterval = getMillis(properties, env, PropertyKey.QWP_UDP_COMMIT_INTERVAL, COMMIT_INTERVAL_DEFAULT);
            if (qwpUdpCommitInterval < 1L) {
                throw new ServerConfigurationException(
                        PropertyKey.QWP_UDP_COMMIT_INTERVAL.getPropertyPath()
                                + " must be at least 1ms"
                );
            }
            this.qwpUdpCommitInterval = qwpUdpCommitInterval;
            int qwpUdpMaxUncommittedDatagrams = getInt(properties, env, PropertyKey.QWP_UDP_MAX_UNCOMMITTED_DATAGRAMS, 1_048_576);
            if (qwpUdpMaxUncommittedDatagrams < 1) {
                throw new ServerConfigurationException(
                        PropertyKey.QWP_UDP_MAX_UNCOMMITTED_DATAGRAMS.getPropertyPath()
                                + " must be at least 1"
                );
            }
            this.qwpUdpMaxUncommittedDatagrams = qwpUdpMaxUncommittedDatagrams;
            this.qwpUdpMsgBufferSize = getIntSize(properties, env, PropertyKey.QWP_UDP_MSG_BUFFER_SIZE, 65_536);
            if (qwpUdpMsgBufferSize < QwpConstants.HEADER_SIZE) {
                throw new ServerConfigurationException(
                        PropertyKey.QWP_UDP_MSG_BUFFER_SIZE.getPropertyPath()
                                + " must be at least "
                                + QwpConstants.HEADER_SIZE
                                + " bytes"
                );
            }
            this.qwpUdpMsgCount = getInt(properties, env, PropertyKey.QWP_UDP_MSG_COUNT, 10_000);
            if (qwpUdpMsgCount < 1) {
                throw new ServerConfigurationException(
                        PropertyKey.QWP_UDP_MSG_COUNT.getPropertyPath()

View on GitHub (pinned to 6610ab113b)

Solutions

1. Set qwp.udp.max.uncommitted.datagrams to a positive count, e.g. 1000000
2. If interval commits should dominate, raise this number instead of zeroing it
3. Leave the key unset to inherit the 1,048,576 default

Example fix

# before
qwp.udp.max.uncommitted.datagrams=0

# after
qwp.udp.max.uncommitted.datagrams=1000000

int datagrams = Integer.parseInt(firstNonBlank(props.get("qwp.udp.max.uncommitted.datagrams"), "1048576"));
if (datagrams < 1) {
    throw new IllegalStateException("qwp.udp.max.uncommitted.datagrams must be >= 1, got " + datagrams);
}

When it happens

Trigger: Explicitly setting qwp.udp.max.uncommitted.datagrams=0 or a negative number in server.conf or via QDB_ environment variables. Simple '< 1' check right after getInt().

Common situations: Disabling count-based commits in favor of interval commits by zeroing the knob (use a very large value instead); placeholder zeros from config templates; units confusion with the byte-size sibling keys (this one is a plain count, not a size).

Related errors

• ${PropertyKey.QWP_UDP_COMMIT_INTERVAL.propertyPath} must be
• ${PropertyKey.QWP_UDP_MSG_COUNT.propertyPath} must be at lea
• ${PropertyKey.QWP_MAX_ROWS_PER_TABLE.propertyPath} must be b
• ${PropertyKey.QWP_MAX_TABLES_PER_CONNECTION.propertyPath} mu
• ${PropertyKey.QWP_MAX_UNCOMMITTED_ROWS.propertyPath} must be

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