JetBrains/intellij-community · error · ExecutionException

error.unable.to.create.sapidattachingconnector

error.unable.to.create.sapidattachingconnector

Error message

Unable to create SAPIDAttachingConnector

What it means

Thrown by SAPidRemoteConnection.getConnector when loading sun.jvm.hotspot.jdi.SAPIDAttachingConnector via reflection from sa-jdi.jar (located under JAVA_HOME/lib, ../lib on macOS, or the configured fallback path) with JBSAJDIClassLoader fails, or instantiating it fails. Without this connector, PID-based attach through the Serviceability Agent cannot proceed.

Source

Thrown at java/debugger/impl/src/com/intellij/debugger/impl/attach/SAPidRemoteConnection.java:39

  private final String mySAJarPath;

  public SAPidRemoteConnection(String pid, String saJarPath) {
    super(pid);
    mySAJarPath = saJarPath;
  }

  @Override
  public AttachingConnector getConnector(DebugProcessImpl debugProcess) throws ExecutionException {
    try {
      Path saJarPath = Paths.get(mySAJarPath);
      Class<?> connectorClass = Class.forName("sun.jvm.hotspot.jdi.SAPIDAttachingConnector",
                                              true,
                                              new JBSAJDIClassLoader(getBaseSAJDIClassLoader(saJarPath), saJarPath));
      return (AttachingConnector)connectorClass.getDeclaredConstructor().newInstance();
    }
    catch (Exception e) {
      throw new ExecutionException(JavaDebuggerBundle.message("error.unable.to.create.sapidattachingconnector"), e);
    }
  }

  private static synchronized @NotNull ClassLoader getBaseSAJDIClassLoader(Path fallback) {
    if (BASE_SA_JDI_CLASS_LOADER == null) {
      Path saJdiJar = Paths.get(SystemProperties.getJavaHome(), "lib/sa-jdi.jar");
      if (!Files.exists(saJdiJar)) {
        saJdiJar = Paths.get(SystemProperties.getJavaHome(), "../lib/sa-jdi.jar"); // MacOS
        if (!Files.exists(saJdiJar)) {
          saJdiJar = fallback;
        }
      }
      BASE_SA_JDI_CLASS_LOADER = new JBSAJDIClassLoader(SAPidRemoteConnection.class.getClassLoader(), saJdiJar);
    }
    return BASE_SA_JDI_CLASS_LOADER;
  }

  private static class JBSAJDIClassLoader extends URLClassLoader {

View on GitHub (pinned to be881553f2)

Solutions

1. Run the IDE on a full JDK that includes lib/sa-jdi.jar (e.g. a matching Temurin/Corretto full JDK)
2. Verify the fallback SA jar path configured for the attach is valid and matches the IDE JVM version
3. Prefer socket/agent-based attach: start the target with -agentlib:jdwp and attach by host:port instead of PID

Example fix

# before: IDE runs on jre-17 (no lib/sa-jdi.jar) -> error on PID attach

# after: run IDE on jdk-17 full distribution containing lib/sa-jdi.jar

Path saJdi = Path.of(SystemProperties.getJavaHome(), "lib/sa-jdi.jar");
if (!Files.exists(saJdi)) {
  saJdi = Path.of(SystemProperties.getJavaHome(), "../lib/sa-jdi.jar");
}
if (!Files.exists(saJdi)) {
  // skip PID attach via SA; suggest socket attach instead
}

try {
  connector = connection.getConnector(debugProcess);
} catch (ExecutionException e) {
  // fall back to standard SocketAttachingConnector using host:port
}

When it happens

Trigger: getConnector() calls Class.forName('sun.jvm.hotspot.jdi.SAPIDAttachingConnector', true, new JBSAJDIClassLoader(getBaseSAJDIClassLoader(saJarPath), saJarPath)) then getDeclaredConstructor().newInstance(); ClassNotFoundException (missing sa-jdi.jar), linkage errors, or instantiation exceptions are all wrapped as ExecutionException(error.unable.to.create.sapidattachingconnector).

Common situations: IDE running on a JDK that ships no lib/sa-jdi.jar (many JDK 9+ builds and JREs); corrupt or incompatible sa-jdi.jar version vs the running IDE JVM; custom fallback SA jar path misconfigured; attaching by PID on a JDK where SA JDI was removed.

Related errors

• Unable to start sa-jdwp server
• Error creating evaluation class loader:
• ATTACH_VM_FAILED
• Interface method invocation is not supported in JVM {}. Use
• There is no executable code at {0}:{1}

AI-assisted analysis of JetBrains/intellij-community@be881553f2 (2026-08-14). Data as JSON: /api/errors/080fa7aa7861dfc2. Report an issue: GitHub.