apache/pulsar · error · RestException

interval must be greater than or equal to 0

Error message

interval must be greater than or equal to 0

What it means

Thrown by internalSetDeduplicationSnapshotInterval when setting the namespace deduplication snapshot interval to a negative value. The interval is a number of seconds between producer-dedup snapshots; only null (unset) or values >= 0 are allowed. Rejected with HTTP 412 PRECONDITION_FAILED before any policy update.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java:2445

                } else {
                    int defaultNumberOfBundles = config().getDefaultNumberOfNamespaceBundles();
                    policies.bundles = getBundles(defaultNumberOfBundles);
                }

                if (policies.persistence != null) {
                    validatePersistencePolicies(policies.persistence);
                }

                if (policies.retention_policies != null) {
                    validateRetentionPolicies(policies.retention_policies);
                }
            });
    }

    protected void internalSetDeduplicationSnapshotInterval(Integer interval) {
        validateNamespacePolicyOperation(namespaceName, PolicyName.DEDUPLICATION_SNAPSHOT, PolicyOperation.WRITE);
        if (interval != null && interval < 0) {
            throw new RestException(Status.PRECONDITION_FAILED, "interval must be greater than or equal to 0");
        }
        internalSetPolicies("deduplicationSnapshotIntervalSeconds", interval);
    }

    protected void internalSetMaxProducersPerTopic(Integer maxProducersPerTopic) {
        validateNamespacePolicyOperation(namespaceName, PolicyName.MAX_PRODUCERS, PolicyOperation.WRITE);
        validatePoliciesReadOnlyAccess();

        try {
            if (maxProducersPerTopic != null && maxProducersPerTopic < 0) {
                throw new RestException(Status.PRECONDITION_FAILED,
                        "maxProducersPerTopic must be 0 or more");
            }
            updatePolicies(namespaceName, policies -> {
                policies.max_producers_per_topic = maxProducersPerTopic;
                return policies;
            });
            log.info()

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a value >= 0 (0 can mean take snapshots as per default cadence, positive = interval seconds)
2. Use null (or omit the parameter) to clear/unset the interval instead of -1
3. Fix the source config/script that computed the negative value

Example fix

// before
admin.namespaces().setDeduplicationSnapshotInterval("my-tenant/my-ns", -1); // 412
// after
admin.namespaces().setDeduplicationSnapshotInterval("my-tenant/my-ns", 10); // every 10s
// or to unset:
admin.namespaces().setDeduplicationSnapshotInterval("my-tenant/my-ns", null);

if (interval != null && interval < 0) {
    throw new IllegalArgumentException("Deduplication snapshot interval must be >= 0 or null");
}

boolean isValidInterval(Integer interval) { return interval == null || interval >= 0; }

try {
    admin.namespaces().setDeduplicationSnapshotInterval(ns, interval);
} catch (PulsarAdminException.PreconditionFailedException e) {
    log.error("Interval {} invalid; pass null to unset", interval);
    throw e;
}

When it happens

Trigger: POST /namespaces/{ns}/deduplicationSnapshotInterval with a negative integer; a caller passing -1 to mean 'disable' when the correct unset is null; config templates where an empty variable defaulted to a negative number.

Common situations: Scripts using -1 as a sentinel for 'disabled'; typos in generated config; CLI wrappers that don't validate the argument before calling the admin API.

Related errors

• Topic name is not valid
• Partitioned Topic Name should not contain '-partition-'
• Invalid value for message TTL
• maxProducersPerTopic must be 0 or more
• maxConsumersPerTopic must be 0 or more

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/0ec74b41d13ee559. Report an issue: GitHub.