pinpoint-apm/pinpoint · error · IllegalArgumentException

eventIdentifier cannot be less than 0

Error message

eventIdentifier cannot be less than 0

What it means

AgentLifeCycleBo's constructor validates that the eventIdentifier (the agent's startTimestamp, used as a unique lifecycle event key) is non-negative before persisting the lifecycle event to HBase. A negative value means corrupted or mis-decoded input, so the library refuses to build the business object. This is an eager fail-fast guard on data integrity.

Source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/AgentLifeCycleBo.java:51

    private final byte version;
    @NonNull
    private final String agentId;
    private final long startTimestamp;
    private final long eventTimestamp;
    private final long eventIdentifier;
    private final AgentLifeCycleState agentLifeCycleState;
    
    public AgentLifeCycleBo(String agentId, long startTimestamp, long eventTimestamp, long eventIdentifier, AgentLifeCycleState agentLifeCycleState) {
        this(CURRENT_VERSION, agentId, startTimestamp, eventTimestamp, eventIdentifier, agentLifeCycleState);
    }

    public AgentLifeCycleBo(int version, String agentId, long startTimestamp, long eventTimestamp, long eventIdentifier, AgentLifeCycleState agentLifeCycleState) {
        this.version = ByteUtils.toUnsignedByte(version);
        this.agentId = StringPrecondition.requireHasLength(agentId, "agentId");

        if (eventIdentifier < 0) {
            throw new IllegalArgumentException("eventIdentifier cannot be less than 0");
        }
        this.startTimestamp = NumberPrecondition.requirePositiveOrZero(startTimestamp, "startTimestamp");
        this.eventTimestamp = NumberPrecondition.requirePositiveOrZero(eventTimestamp, "eventTimestamp");
        this.eventIdentifier = eventIdentifier;
        this.agentLifeCycleState = Objects.requireNonNull(agentLifeCycleState, "agentLifeCycleState");
    }

    public int getVersion() {
        return Byte.toUnsignedInt(this.version);
    }

    public String getAgentId() {
        return agentId;
    }

    public long getStartTimestamp() {
        return startTimestamp;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check the caller that computes eventIdentifier (usually the agent startTimestamp extracted from a row key) and fix the byte-decoding offset/length
2. Log the raw input bytes/value before constructing AgentLifeCycleBo to find where the negative value originates
3. If the value can legitimately be 0, pass 0 rather than a negative sentinel; the constructor accepts 0
4. Reject the record upstream instead of constructing the BO so the error is handled where the data was read

Example fix

// before
long eventIdentifier = BufferFactory.resolve(rowKey.slice(0, 8)).readLong(); // misaligned -> negative
new AgentLifeCycleBo(version, agentId, start, event, eventIdentifier, state);
// after
long eventIdentifier = new FixedBuffer(rowKey).readLong();
if (eventIdentifier < 0) { log.warn("bad eventIdentifier {}", eventIdentifier); return; }
new AgentLifeCycleBo(version, agentId, start, event, eventIdentifier, state);

if (eventIdentifier < 0) { log.warn("invalid eventIdentifier {} for agent {}", eventIdentifier, agentId); return; }

boolean isValidEventIdentifier(long v) { return v >= 0; }

try { new AgentLifeCycleBo(v, id, st, et, eid, state); } catch (IllegalArgumentException e) { log.warn("skipping lifecycle event: {}", e.getMessage()); }

When it happens

Trigger: Calling new AgentLifeCycleBo(version, agentId, startTimestamp, eventTimestamp, eventIdentifier, state) with a negative eventIdentifier, e.g. when deserializing a row key or agent-start timestamp that was decoded incorrectly or is corrupt.

Common situations: Corrupt or truncated HBase row keys, wrong endOffset/limit when slicing the agent-start-timestamp bytes out of a key, or agents from buggy collectors writing malformed timestamps.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• annotationKey name must not be empty
• matcher type must not be empty
• Unknown matcher type :
• value
• negative cache size:${size}

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/dba45f52ac529065. Report an issue: GitHub.