pinpoint-apm/pinpoint · error · IllegalArgumentException

Unexpected TraceId type: ${traceId}

Error message

Unexpected TraceId type: ${traceId}

What it means

TraceIdMapStructUtils.newTransactionId converts a TraceId into a protobuf PTransactionId. It expects the traceId to be either a TransactionId (agentId/agentStartTime/transactionSequence fields) or a supported TraceId variant; any other runtime type reaches the final throw of IllegalArgumentException. This is a defensive check against passing the wrong TraceId implementation into the gRPC mapper.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/grpc/mapper/TraceIdMapStructUtils.java:50

public class TraceIdMapStructUtils {
    @Qualifier
    @Target(ElementType.METHOD)
    @Retention(RetentionPolicy.CLASS)
    public @interface ToTransactionId {
    }

    @ToTransactionId
    public static PTransactionId newTransactionId(TraceId traceId) {
        if (traceId instanceof DefaultTraceId) {
            DefaultTraceId defaultTraceId = (DefaultTraceId) traceId;
            TransactionId txId = defaultTraceId.getInternalTransactionId();
            final PTransactionId.Builder builder = PTransactionId.newBuilder();
            builder.setAgentId(txId.getAgentId());
            builder.setAgentStartTime(txId.getAgentStartTime());
            builder.setSequence(txId.getTransactionSequence());
            return builder.build();
        }
        throw new IllegalArgumentException("Unexpected TraceId type: " + traceId);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure the TraceId passed in is the profiler's TransactionId implementation (DefaultTransactionId) as produced by the trace context.
2. In tests, use the real TraceIdFactory/TransactionId instead of mock TraceId implementations.
3. Align Pinpoint component versions so the TraceId interface/implementation hierarchy matches the mapper's expectations.
4. Convert the custom TraceId to a TransactionId (agentId, agentStartTime, transactionSequence) before calling newTransactionId.

Example fix

// before
PTransactionId pId = TraceIdMapStructUtils.newTransactionId(mockTraceId);

// after
TraceId realTxId = traceContext.createTraceId(agentId, agentStartTime, transactionSequence);
PTransactionId pId = TraceIdMapStructUtils.newTransactionId(realTxId);

if (!(traceId instanceof TransactionId)) {
    throw new IllegalArgumentException("Expected TransactionId, got: " + traceId.getClass());
}

static boolean isTransactionId(TraceId traceId) {
    return traceId instanceof TransactionId
            || (traceId.getAgentId() != null && traceId.getTransactionSequence() != null);
}

try {
    PTransactionId pId = TraceIdMapStructUtils.newTransactionId(traceId);
} catch (IllegalArgumentException e) {
    logger.warn("Unexpected TraceId implementation {}: {}", traceId.getClass(), e.getMessage());
    pId = buildPTransactionIdFromFields(traceId); // manual fallback
}

When it happens

Trigger: Calling newTransactionId (directly or via Span/TSpan mapping) with a TraceId implementation whose concrete type is not the expected TransactionId class — e.g. a custom TraceId, a mock, or a TraceId from a different profiler version/lineage.

Common situations: Custom trace implementations from plugins or test stubs; mixing pinpoint commons/profiler versions where TraceId interfaces changed; passing Span's traceId from a mocked/span-impl variant in unit tests into the gRPC mapper.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• spanEventList is empty.
• first SpanEvent is null
• unsupported message
• UNSUPPORTED_OPERATION
• startTime not recorded

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