pinpoint-apm/pinpoint · error

pinpoint start failed.

Error message

pinpoint start failed.

What it means

The catch-all in PinpointStarter.start(): after properties are validated and the agent class loaded reflectively, any unexpected exception during reflective invocation of start()/registerStopHandler() is logged as this warning and agent startup returns false. It signals a bug or an unchecked environment problem, since checked failures are handled earlier.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointStarter.java:117

            AgentBootLoader agentBootLoader = new AgentBootLoader(agentType.getClassName(), agentClassLoader);
            logger.info(String.format("pinpoint agent [%s] starting...", agentType));

            final List<Path> pluginJars = agentDirectory.getPlugins();
            AgentOption option = createAgentOption(
                    instrumentation,
                    properties,
                    agentArgs,
                    agentDirectory.getAgentDirPath(),
                    pluginJars,
                    agentDirectory.getBootDir().getJarPath());
            Object agent = agentBootLoader.boot(option);
            Class<?> agentClazz = agent.getClass();
            agentClazz.getMethod("start").invoke(agent);
            agentClazz.getMethod("registerStopHandler").invoke(agent);
            logger.info("pinpoint agent started normally.");
        } catch (Exception e) {
            // unexpected exception that did not be checked above
            logger.warn("pinpoint start failed.", e);
            return false;
        }
        return true;
    }

    // TestAgent only
    public static final String IMPORT_PLUGIN = "profiler.plugin.import-plugin";


    private Properties loadProperties() {

        final Path agentDirPath = agentDirectory.getAgentDirPath();
        final Path profilesPath = agentDirectory.getProfilesPath();
        final List<Path> profileDirs = agentDirectory.getProfileDirs();

        final Properties javaSystemProperty = copyJavaSystemProperty();
        final Properties osEnvProperty = copyOSEnvVariables();

View on GitHub (pinned to 744c3d3075)

Solutions

1. Inspect the full chained stack trace under this warning for the root cause
2. Verify collector host/port and network connectivity from the agent
3. Ensure all jars in the agent directory come from the same Pinpoint version
4. Check JVM support for your Pinpoint version and enable finer log levels for the starter

// shell: pre-launch checks
nc -z "$COLLECTOR_HOST" "$COLLECTOR_PORT" || echo "collector unreachable"
ls "$AGENT_DIR"/lib | awk -F- '{print $1}' | sort -u | grep -c . # spot mixed versions

When it happens

Trigger: The loaded PinpointAgent class throws during initialization — e.g. failed network connection to collector, missing plugin dependencies, config values invalid only at runtime, or NoSuchMethod/IllegalAccessException from a classloader/version mismatch.

Common situations: Collector unreachable (profiler.config transport errors surfacing as unexpected exceptions); mismatched agent-module jar versions inside the agent dir; plugin jars incompatible with the agent version; JVM not officially supported.

Related errors

• Cannot access ClassLoader.defineClass(String, byte[], int, i
• Cannot access URLClassLoader.addURL(URL)
• initialize fail Caused by:
• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:

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