pinpoint-apm/pinpoint · error · IllegalStateException

Unknown SpanSenderType: ${spanSenderType}

Error message

Unknown SpanSenderType: ${spanSenderType}

What it means

GrpcModule.bindSpanDataSender switches on the configured SpanSenderType to bind either a batched or streaming gRPC span sender. An unrecognized type hits the default branch and throws IllegalStateException('Unknown SpanSenderType: ...'). The enum is internal, so this usually means a bad config mapping or a version mismatch.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/module/GrpcModule.java:225

        TypeLiteral<SpanProcessor<PSpan.Builder, PSpanChunk.Builder>> spanPostProcessorType = new TypeLiteral<SpanProcessor<PSpan.Builder, PSpanChunk.Builder>>() {
        };
        bind(spanPostProcessorType).toProvider(GrpcSpanProcessorProvider.class).in(Scopes.SINGLETON);

        TypeLiteral<DataSender<SpanType>> spanDataSenderType = new TypeLiteral<DataSender<SpanType>>() {
        };
        Key<DataSender<SpanType>> spanDataSender = Key.get(spanDataSenderType, SpanDataSender.class);

        SpanSenderType spanSenderType = grpcTransportConfig.getSpanSenderType();
        logger.info("SpanSenderType: {}", spanSenderType);
        switch (spanSenderType) {
            case BATCH:
                bind(spanDataSender).toProvider(SpanBatchGrpcDataSenderProvider.class).in(Scopes.SINGLETON);
                break;
            case STREAM:
                bind(spanDataSender).toProvider(SpanGrpcDataSenderProvider.class).in(Scopes.SINGLETON);
                break;
            default:
                throw new IllegalStateException("Unknown SpanSenderType: " + spanSenderType);
        }
        expose(spanDataSender);
    }


    private GrpcTransportConfig loadGrpcTransportConfig() {
        GrpcTransportConfig grpcTransportConfig = new GrpcTransportConfig();
        grpcTransportConfig.read(profilerConfig.getProperties()::getProperty);
        logger.info("{}", grpcTransportConfig);
        return grpcTransportConfig;
    }

}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set the span sender type to a supported value (e.g. GRPC for batched or STREAM for streaming transport)
2. Check profiler config keys around span sender/transport for typos or copied-in invalid values
3. Use agent jars all from the same release so the enum has the expected constants
4. Inspect how the value is parsed (valueOf) and make sure the config string matches a valid enum constant

Example fix

// before
profiler.span.grpc.senderType=UDP  // not a gRPC sender type
// after
profiler.span.grpc.senderType=GRPC

String t = config.readString("profiler.span.sender.type", "GRPC");
if (!t.equalsIgnoreCase("GRPC") && !t.equalsIgnoreCase("STREAM")) {
    throw new IllegalArgumentException("profiler.span.sender.type must be GRPC or STREAM, got: " + t);
}

When it happens

Trigger: The profiler's span sender type value resolves to something other than GRPC/STREAM (the supported cases) when configuring the gRPC module — e.g. an unknown string mapped into SpanSenderType or an enum extended in one jar but not another.

Common situations: Typos or unsupported values in profiler.span.sender type / transport config, hand-edited pinpoints config files, or mixed agent jar versions where a new SpanSenderType constant is read by older code.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown InstrumentEngine:${instrumentEngine}
• unknown ${GRPC_TRACE_VERSION_KEY}:${version}
• Unknown AgentType:
• service type name must not be empty
• Invalid type provider definition :

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