What causes "class name must not be null" in pinpoint-apm/pinpoint?

Ensure the class name is resolved and non-null before conversion; fail earlier with a clear config error.

pinpoint-apm/pinpoint · error · IllegalArgumentException

class name must not be null

Error message

class name must not be null

What it means

ClassUtils.toInternalName converts a Java binary class name to JVM internal form by replacing '.' with '/' (e.g. com.foo.Bar -> com/foo/Bar). A null class name cannot be converted, so the method throws IllegalArgumentException as a precondition check.

Solutions

Ensure the class name is resolved and non-null before conversion; fail earlier with a clear config error.
Guard the call site with a null check or Objects.requireNonNull with a descriptive message.
Trace where the null originates — usually a missing configuration entry or an unloaded/unknown class.

Example fix

// before
String internal = ClassUtils.toInternalName(config.getTargetClass());
// after
String target = config.getTargetClass();
if (target == null) {
    throw new IllegalStateException("targetClass is not configured");
}
String internal = ClassUtils.toInternalName(target);

Defensive patterns

Strategy: type-guard

Validate before calling

if (className == null || className.isEmpty()) {
    throw new IllegalStateException("class name not configured");
}

Type guard

boolean hasClassName(String cn) { return cn != null && !cn.isEmpty(); }

Try / catch

try {
    return ClassUtils.toInternalName(className);
} catch (IllegalArgumentException e) {
    throw new ConfigurationException("Target class name is null; check agent config", e);
}

Prevention

Resolve configuration into non-null values at startup with fail-fast checks
Avoid passing raw reflection lookups (possibly null) into name converters
Validate instrumentation target config before use

When it happens

Trigger: Calling ClassUtils.toInternalName(null), typically when a class name was obtained from a lookup that returned null (Class.getName on a missing class, config field not set, or reflection metadata absent).

Common situations: Instrumentation/agent configuration where a target class name placeholder is unset, or code paths building bytecode names from nullable reflection results.

Related errors

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

Appendix: source

Thrown at commons/src/main/java/com/navercorp/pinpoint/common/util/ClassUtils.java:70

        Objects.requireNonNull(fqcn, "fqcn");

        final int lastPackageSeparatorIndex = fqcn.lastIndexOf(packageSeparator);
        if (lastPackageSeparatorIndex == -1) {
            return defaultValue;
        }
        return fqcn.substring(0, lastPackageSeparatorIndex);
    }

    public static String getPackageName(String fqcn) {
        return getPackageName(fqcn, PACKAGE_SEPARATOR, "");
    }

    /**
     * convert "." based name to "/" based internal name.
     */
    public static String toInternalName(final String className) {
        if (className == null) {
            throw new IllegalArgumentException("class name must not be null");
        }
        return className.replace('.', '/');
    }
}

View on GitHub (pinned to 744c3d3075)