apache/pulsar · error · IllegalArgumentException

Invalid format for fully qualified instance name:

Error message

Invalid format for fully qualified instance name: 

What it means

FunctionInstanceId parses a fully qualified instance name expected to be 'tenant/namespace/name:instanceId'. The constructor splits on '/' and throws IllegalArgumentException if the string does not contain exactly 3 slash-separated parts.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionInstanceId.java:35

 * under the License.
 */
package org.apache.pulsar.functions.utils;

import lombok.Data;

@Data
public class FunctionInstanceId {

    private String tenant;
    private String namespace;
    private String name;
    private int instanceId;

    public FunctionInstanceId(String fullyQualifiedInstanceName) {
        String[] t1 = fullyQualifiedInstanceName.split("/");

        if (t1.length != 3) {
            throw new IllegalArgumentException(
                    "Invalid format for fully qualified instance name: " + fullyQualifiedInstanceName);
        }

        this.tenant = t1[0];
        this.namespace = t1[1];

        int instanceIdDelimiterIndex = t1[2].lastIndexOf(':');

        if (instanceIdDelimiterIndex < 0) {
            throw new IllegalArgumentException(
                    "Invalid format for fully qualified instance name: " + fullyQualifiedInstanceName);
        }

        this.name = t1[2].substring(0, instanceIdDelimiterIndex);
        this.instanceId = Integer.parseInt(t1[2].substring(instanceIdDelimiterIndex + 1));
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Pass the complete 'tenant/namespace/functionName:instanceId' string.
2. Derive the instance name from FunctionInstanceId's formatting methods instead of hand-building the string.
3. Pre-validate with a regex like ^[^/]+/[^/]+/[^/]+:\d+$ before constructing.
4. Check the caller for string truncation or use of the wrong identifier (function vs instance).

Example fix

// before
new FunctionInstanceId("tenant/ns/myfunc"); // missing :instanceId
// after
new FunctionInstanceId("tenant/ns/myfunc:0");

java.util.regex.Pattern P = java.util.regex.Pattern.compile("[^/]+/[^/]+/[^/]+\\:\\d+");
if (fullyQualifiedInstanceName == null || !P.matcher(fullyQualifiedInstanceName).matches()) {
    throw new IllegalArgumentException("Expected tenant/namespace/name:instanceId, got: " + fullyQualifiedInstanceName);
}

static boolean isFullyQualifiedInstanceName(String s) {
    return s != null && s.matches("[^/]+/[^/]+/[^/]+:\\d+");
}

try {
    FunctionInstanceId id = new FunctionInstanceId(name);
} catch (IllegalArgumentException e) {
    log.error("Bad instance name '{}': expected tenant/namespace/name:instanceId", name);
}

When it happens

Trigger: Calling new FunctionInstanceId(String) with a name missing '/' separators (e.g. only 'tenant/namespace' or a bare function name) or containing extra '/' segments (e.g. full topic-style names).

Common situations: Passing a function name instead of an instance name; passing a Pulsar topic or FQFN without the ':instanceId' suffix; copying names from logs that trimmed parts.

Related errors

• Invalid txnId key:
• Invalid value %s for the position. Allowed values are [lates
• Invalid string to parse WorkerInfo : ${str}
• Invalid topic domain: '${value}'
• Schema should not be null.

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/2b600afe6d16f083. Report an issue: GitHub.