apache/pulsar · error · IOException

Allowed offset for athenz role token verification must not b

Error message

Allowed offset for athenz role token verification must not be negative

What it means

initialize() parses the allowed clock offset for role token verification and rejects negative values with this IOException. A negative offset would shift token validity windows in an unsupported way, so the provider refuses to start.

Source

Thrown at pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java:88

            domainNames = (String) config.getProperty(DOMAIN_NAME_LIST);
        } else if (!StringUtils.isEmpty(System.getProperty(SYS_PROP_DOMAIN_NAME_LIST))) {
            domainNames = System.getProperty(SYS_PROP_DOMAIN_NAME_LIST);
        } else {
            throw new IOException("No athenz domain name specified");
        }

        domainNameList = Lists.newArrayList(domainNames.split(","));
        log.info().attr("domainNames", domainNameList).log("Supported domain names for Athenz");

        if (!StringUtils.isEmpty(System.getProperty(SYS_PROP_ALLOWED_OFFSET))) {
            try {
                allowedOffset = Integer.parseInt(System.getProperty(SYS_PROP_ALLOWED_OFFSET));
            } catch (NumberFormatException e) {
                throw new IOException("Invalid allowed offset for athenz role token verification specified", e);
            }

            if (allowedOffset < 0) {
                throw new IOException("Allowed offset for athenz role token verification must not be negative");
            }
        }

        log.info().attr("allowedOffsetSeconds", allowedOffset).log("Allowed offset for athenz role token verification");
    }

    @Override
    public String getAuthMethodName() {
        return "athenz";
    }

    @Override
    public void incrementFailureMetric(Enum<?> errorCode) {
        authenticationMetrics.recordFailure(errorCode);
    }

    @Override
    public String authenticate(AuthenticationDataSource authData) throws AuthenticationException {

View on GitHub (pinned to 820761864e)

Solutions

Set the offset system property to a non-negative integer of seconds, e.g. 0 or 30.
Use 0 to enforce strict timestamp validation with no skew tolerance.
Remove the property to fall back to the library default.

Example fix

// before
-Dathenz.allowed.offset=-30
// after
-Dathenz.allowed.offset=30

Defensive patterns

Strategy: validation

Validate before calling

String off = System.getProperty(ATHENZ_SYS_PROP_ALLOWED_OFFSET);
if (off != null && !off.isEmpty() && Integer.parseInt(off.trim()) < 0) {
    throw new IllegalArgumentException("allowed offset must be >= 0");
}

Try / catch

try {
    provider.initialize(config);
} catch (IOException e) {
    if (e.getMessage().contains("must not be negative")) {
        log.error("Clamp the offset system property to a non-negative integer");
    }
    throw e;
}

Prevention

Use 0 for strict validation rather than negative offsets.
Clamp parsed values with Math.max(0, value) in config tooling.
Document valid ranges for the offset property in deployment templates.

When it happens

Trigger: System property SYS_PROP_ALLOWED_OFFSET is set to a negative integer such as -1 or -60.

Common situations: Operator intended to shrink tolerance and used a negative number; copy-pasted offset tuning advice meant for a different (signed) setting.

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.

Related errors

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