What causes "Unknown SpanSenderType: ${value}" in pinpoint-apm/pinpoint?

Use one of the exact SpanSenderType enum names in the config (case-insensitive), e.g. GRPC.

pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown SpanSenderType: ${value}

Error message

Unknown SpanSenderType: ${value}

What it means

SpanSenderType.fromValue resolves a configuration string to a SpanSenderType enum by case-insensitive name matching. If the given value matches none of the enum constants, it throws IllegalArgumentException listing the unknown value. This guards against typos or unsupported sender implementations in agent configuration.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/grpc/config/SpanSenderType.java:39

 */
public enum SpanSenderType {
    BATCH,
    STREAM;

    public static SpanSenderType defaultType() {
        return BATCH;
    }

    public static SpanSenderType fromValue(String value) {
        if (value == null) {
            return defaultType();
        }
        for (SpanSenderType type : values()) {
            if (type.name().equalsIgnoreCase(value)) {
                return type;
            }
        }
        throw new IllegalArgumentException("Unknown SpanSenderType: " + value);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

Use one of the exact SpanSenderType enum names in the config (case-insensitive), e.g. GRPC.
Print accepted values: check SpanSenderType enum constants in the same Pinpoint version you run.
Remove stale config from an older Pinpoint version if the enum value was renamed or removed.
Update the Pinpoint agent version if the desired sender type only exists in a newer release.

Example fix

// before (config)
profiler.span.sender.type=GRPC_STREAMING

// after
profiler.span.sender.type=GRPC

Defensive patterns

Strategy: validation

Validate before calling

String senderType = properties.getProperty("profiler.span.sender.type", "GRPC").trim();
boolean valid = Arrays.stream(SpanSenderType.values())
        .anyMatch(t -> t.name().equalsIgnoreCase(senderType));
if (!valid) throw new IllegalStateException("Invalid profiler.span.sender.type: " + senderType);

Try / catch

try {
    SpanSenderType type = SpanSenderType.fromValue(configValue);
} catch (IllegalArgumentException e) {
    logger.error("Bad sender type '{}', falling back to GRPC", configValue);
    SpanSenderType type = SpanSenderType.GRPC;
}

Prevention

Copy enum names exactly from SpanSenderType in your agent version (matching is case-insensitive but names must exist).
When upgrading Pinpoint, diff your config keys/values against the new version's defaults.
Validate config at startup with a fail-fast script before deploying agents.

When it happens

Trigger: Setting the span sender type profiler config property (e.g. profiler.span.sender.type or equivalent) to a string other than the defined enum names (case-insensitive), then starting the agent — fromValue is invoked during config parsing/initialization.

Common situations: Typo in pinpoint.config value (e.g. 'GRPC_HTTP' vs supported names); copying config from another Pinpoint version where the enum constant was renamed/removed; extra whitespace is trimmed via toUpperCase/equalsIgnoreCase but non-matching names like 'grpcv2' fail.

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

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