pinpoint-apm/pinpoint · error · IllegalArgumentException

the key must contain ':' key:

Error message

the key must contain ':' key:

What it means

RedisKVSubChannelProvider.getSubChannel requires keys of the form '<duration>:<value>' because KeyValueTokenizer.tokenize(key, ":") must yield both a key (parsed with Duration.parse) and a value. When no ':' is present, tokenize returns null and an IllegalArgumentException is thrown. The duration portion must also be a valid ISO-8601 duration (e.g. PT1S).

Solutions

1. Format the key as an ISO-8601 duration followed by ':' and the key name, e.g. "PT30S:mykey".
2. Ensure the segment before ':' is Duration.parse-compatible (PT10S, PT1M, ...) or a Duration.parse exception follows.
3. If the key comes from external config, add a format check before calling getSubChannel.

Example fix

// before
provider.getSubChannel("mykey");
// after
provider.getSubChannel("PT30S:mykey");

if (key == null || !key.contains(":")) throw new IllegalArgumentException("key must be '<ISO-duration>:<name>'");
Duration.parse(key.substring(0, key.indexOf(':'))); // validates duration part

try { provider.getSubChannel(key); } catch (IllegalArgumentException e) { /* fix key format / alert config error */ }

When it happens

Trigger: Calling getSubChannel with a string lacking a ':' separator, e.g. getSubChannel("PT30S") or getSubChannel("mykey").

Common situations: Configuration or code that constructs subscription keys from a single value, forgetting the '<ISO-duration>:<key>' format; refactors that changed the key format; passing a bare channel name from older Pinpoint versions.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• the key must contain ':' key:
• agentStartTimeIndex not found
• application serviceType not found. code:, name:
• Cannot add an existing column family :
• ${fieldName}

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

Appendix: source

Thrown at redis/src/main/java/com/navercorp/pinpoint/channel/redis/kv/RedisKVSubChannelProvider.java:44

/**
 * @author youngjin.kim2
 */
class RedisKVSubChannelProvider implements SubChannelProvider {

    private final RedisTemplate<String, String> template;
    private final Scheduler scheduler;

    RedisKVSubChannelProvider(RedisTemplate<String, String> template, Scheduler scheduler) {
        this.template = Objects.requireNonNull(template, "template");
        this.scheduler = Objects.requireNonNull(scheduler, "scheduler");
    }

    @Override
    public SubChannel getSubChannel(String key) {
        KeyValueTokenizer.KeyValue keyValue = KeyValueTokenizer.tokenize(key, ":");
        if (keyValue == null) {
            throw new IllegalArgumentException("the key must contain ':' key:" + key);
        }
        Duration period = Duration.parse(keyValue.getKey());
        return new RedisKVSubChannel(this.template, this.scheduler, period, keyValue.getValue());
    }

}

View on GitHub (pinned to 744c3d3075)