pinpoint-apm/pinpoint · error · UnsupportedOperationException

unknown ${GRPC_TRACE_VERSION_KEY}:${version}

Error message

unknown ${GRPC_TRACE_VERSION_KEY}:${version}

What it means

TraceDataFormatVersionProvider.getVersion() reads the gRPC trace version from profiler config (key TraceDataFormatVersion.GRPC_TRACE_VERSION_KEY, default 'v2'). Only 'v2' (case-insensitive) is accepted; anything else throws UnsupportedOperationException('unknown <key>:<version>').

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/provider/TraceDataFormatVersionProvider.java:44

/**
 * @author Woonduk Kang(emeroad)
 */
public class TraceDataFormatVersionProvider implements Provider<TraceDataFormatVersion> {
    private final Logger logger = LogManager.getLogger(this.getClass());
    private final TraceDataFormatVersion version;

    @Inject
    public TraceDataFormatVersionProvider(ProfilerConfig profilerConfig) {
        this.version = getVersion(profilerConfig);
        logger.info("TraceDataFormatVersion:{}", this.version);
    }

    private TraceDataFormatVersion getVersion(ProfilerConfig profilerConfig) {
        final String version = profilerConfig.readString(TraceDataFormatVersion.GRPC_TRACE_VERSION_KEY, "v2");
        if ("v2".equalsIgnoreCase(version)) {
            return TraceDataFormatVersion.V2;
        }
        throw new UnsupportedOperationException("unknown " + TraceDataFormatVersion.GRPC_TRACE_VERSION_KEY + ":" + version);
    }

    @Override
    public TraceDataFormatVersion get() {
        return version;
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set the config value to 'v2' (the only supported value) or remove the line to accept the default
2. Check the exact key name and value in pinpoint.config for typos/case issues (value match is case-insensitive)
3. Upgrade the agent if you believe a newer trace format version should be supported
4. Avoid manually editing the version key unless following release-specific migration docs

Example fix

// before
profiler.trace.v2=V3
// after
profiler.trace.v2=v2

String v = config.readString("profiler.trace.v2", "v2");
if (!"v2".equalsIgnoreCase(v.trim())) {
    throw new IllegalArgumentException("profiler.trace.v2 only supports 'v2', got: " + v);
}

try { versionProvider.get(); } catch (UnsupportedOperationException e) { logger.error("Unsupported {} value; use v2", "profiler.trace.v2"); }

When it happens

Trigger: Config property profiler.trace.v2 (gRPC trace version) set to any value other than 'v2'/'V2', e.g. 'v1', 'V3', or a typo like 'v2 '.

Common situations: Users copying older v1-based agent config to a gRPC-based agent, guessing at a 'v3' option that does not exist in their release, or whitespace/typos in pinpoint.config.

Related errors

• Unknown SpanSenderType: ${spanSenderType}
• service type name must not be empty
• Invalid type provider definition :
• invalid full qualified method name(). not found method
• invalid oracle jdbc url:<driverUrl>

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