{"record":{"id":"080fa7aa7861dfc2","repo":"JetBrains/intellij-community","slug":"error-unable-to-create-sapidattachingconnector","errorCode":"error.unable.to.create.sapidattachingconnector","errorMessage":"Unable to create SAPIDAttachingConnector","messagePattern":"Unable to create SAPIDAttachingConnector","errorType":"exception","errorClass":"ExecutionException","httpStatus":null,"severity":"error","filePath":"java/debugger/impl/src/com/intellij/debugger/impl/attach/SAPidRemoteConnection.java","lineNumber":39,"sourceCode":"\n  private final String mySAJarPath;\n\n  public SAPidRemoteConnection(String pid, String saJarPath) {\n    super(pid);\n    mySAJarPath = saJarPath;\n  }\n\n  @Override\n  public AttachingConnector getConnector(DebugProcessImpl debugProcess) throws ExecutionException {\n    try {\n      Path saJarPath = Paths.get(mySAJarPath);\n      Class<?> connectorClass = Class.forName(\"sun.jvm.hotspot.jdi.SAPIDAttachingConnector\",\n                                              true,\n                                              new JBSAJDIClassLoader(getBaseSAJDIClassLoader(saJarPath), saJarPath));\n      return (AttachingConnector)connectorClass.getDeclaredConstructor().newInstance();\n    }\n    catch (Exception e) {\n      throw new ExecutionException(JavaDebuggerBundle.message(\"error.unable.to.create.sapidattachingconnector\"), e);\n    }\n  }\n\n  private static synchronized @NotNull ClassLoader getBaseSAJDIClassLoader(Path fallback) {\n    if (BASE_SA_JDI_CLASS_LOADER == null) {\n      Path saJdiJar = Paths.get(SystemProperties.getJavaHome(), \"lib/sa-jdi.jar\");\n      if (!Files.exists(saJdiJar)) {\n        saJdiJar = Paths.get(SystemProperties.getJavaHome(), \"../lib/sa-jdi.jar\"); // MacOS\n        if (!Files.exists(saJdiJar)) {\n          saJdiJar = fallback;\n        }\n      }\n      BASE_SA_JDI_CLASS_LOADER = new JBSAJDIClassLoader(SAPidRemoteConnection.class.getClassLoader(), saJdiJar);\n    }\n    return BASE_SA_JDI_CLASS_LOADER;\n  }\n\n  private static class JBSAJDIClassLoader extends URLClassLoader {","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/JetBrains/intellij-community/blob/be881553f2a76ac8b4ea53950d93f0de78295c19/java/debugger/impl/src/com/intellij/debugger/impl/attach/SAPidRemoteConnection.java#L21-L57","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run the IDE on a full JDK that includes lib/sa-jdi.jar (e.g. a matching Temurin/Corretto full JDK)","Verify the fallback SA jar path configured for the attach is valid and matches the IDE JVM version","Prefer socket/agent-based attach: start the target with -agentlib:jdwp and attach by host:port instead of PID"],"exampleFix":"# before: IDE runs on jre-17 (no lib/sa-jdi.jar) -> error on PID attach\n\n# after: run IDE on jdk-17 full distribution containing lib/sa-jdi.jar","handlingStrategy":"fallback","validationCode":"Path saJdi = Path.of(SystemProperties.getJavaHome(), \"lib/sa-jdi.jar\");\nif (!Files.exists(saJdi)) {\n  saJdi = Path.of(SystemProperties.getJavaHome(), \"../lib/sa-jdi.jar\");\n}\nif (!Files.exists(saJdi)) {\n  // skip PID attach via SA; suggest socket attach instead\n}","typeGuard":null,"tryCatchPattern":"try {\n  connector = connection.getConnector(debugProcess);\n} catch (ExecutionException e) {\n  // fall back to standard SocketAttachingConnector using host:port\n}","preventionTips":["Run the IDE on a full JDK distribution that includes lib/sa-jdi.jar","Verify the configured fallback SA jar path exists and matches the IDE JVM","Keep -agentlib:jdwp-based attach available as the default alternative"],"tags":["debugger","attach","serviceability-agent","classloader"],"backgroundTag":null,"analyzedSha":"be881553f2a76ac8b4ea53950d93f0de78295c19","analyzedAt":"2026-08-14T14:13:06.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}