apache/pulsar · warning · RestException

Proxy log level can be only [0-2]

Error message

Proxy log level can be only [0-2]

What it means

The proxy log level is an in-memory tuning knob restricted to the range 0-2 (0=off, 1=event, 2=verbose/topic stats). ProxyStats.updateProxyLogLevel validates the path parameter before applying it and returns 412 for out-of-range values, since the proxy cannot express levels outside this range.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/stats/ProxyStats.java:118

            @ApiResponse(responseCode = "503", description = "Proxy service is not initialized") })
    public Map<String, TopicStats> topics() {
        throwIfNotSuperUser("topics");
        Optional<Integer> logLevel = proxyService().getConfiguration().getProxyLogLevel();
        if (!logLevel.isPresent() || logLevel.get() < 2) {
            throw new RestException(Status.PRECONDITION_FAILED, "Proxy doesn't have logging level 2");
        }
        return proxyService().getTopicStats();
    }

    @POST
    @Path("/logging/{logLevel}")
    @Operation(hidden = true, summary = "Change proxy logging level dynamically",
            description = "It only changes the log level in memory; change it in the config file to persist the change")
    @ApiResponses(value = { @ApiResponse(responseCode = "412", description = "Proxy log level can be [0-2]"), })
    public void updateProxyLogLevel(@PathParam("logLevel") int logLevel) {
        throwIfNotSuperUser("updateProxyLogLevel");
        if (logLevel < 0 || logLevel > 2) {
            throw new RestException(Status.PRECONDITION_FAILED, "Proxy log level can be only [0-2]");
        }
        proxyService().setProxyLogLevel(logLevel);
    }

    @GET
    @Path("/logging")
    @Operation(hidden = true, summary = "Get proxy logging")
    public int getProxyLogLevel(@PathParam("logLevel") int logLevel) {
        throwIfNotSuperUser("getProxyLogLevel");
        return proxyService().getProxyLogLevel();
    }

    protected ProxyService proxyService() {
        if (service == null) {
            service = (ProxyService) servletContext.getAttribute(ATTRIBUTE_PULSAR_PROXY_NAME);
            if (service == null) {
                throw new RestException(Status.SERVICE_UNAVAILABLE, "Proxy service is not initialized");
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Use a value between 0 and 2 inclusive — send POST /logging/2 for maximum verbosity
2. Update scripts/runbooks to translate desired verbosity into the 0-2 scale
3. If finer-grained log control is needed, adjust the underlying logback/log4j configuration instead of the proxy REST knob
4. Remember the change is in-memory only; also set proxyLogLevel in the config file to persist

Example fix

// before
curl -X POST .../proxy-stats/logging/3

// after
curl -X POST .../proxy-stats/logging/2

public void setProxyLogLevelSafe(ProxyStats stats, int level) {
    if (level < 0 || level > 2) {
        throw new IllegalArgumentException("Proxy log level must be within [0-2], got " + level);
    }
    stats.updateProxyLogLevel(level);
}

boolean isValidProxyLogLevel(int level) {
    return level >= 0 && level <= 2;
}

try {
    proxyStats.updateProxyLogLevel(requestedLevel);
} catch (RestException e) {
    if (e.getResponseStatus() == 412) {
        LOG.warn("Requested log level {} out of range; using 1", requestedLevel);
        proxyStats.updateProxyLogLevel(1);
    } else {
        throw e;
    }
}

When it happens

Trigger: POST /admin/v2/proxy-stats/logging/{logLevel} with a logLevel < 0 or > 2 (e.g. 3 or -1); a script or dashboard templating an unsupported default level; an operator guessing levels follow java.util.logging or log4j scales (e.g. 4 for DEBUG).

Common situations: Automation using log4j-style numeric levels instead of the proxy's 0-2 scale; typos in runbooks; misconfigured alerting that attempts to 'increase to level 3' for more verbosity.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• Proxy doesn't have logging level 2
• cluster data is required
• Peer cluster ${peerCluster} does not exist
• Cluster ${cluster} does not exist.
• ClusterIds should not be null or empty

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