{"record":{"id":"42606a28e534c9e4","repo":"JetBrains/intellij-community","slug":"unable-to-start-sa-jdwp-server","errorCode":null,"errorMessage":"Unable to start sa-jdwp server","messagePattern":"Unable to start sa-jdwp server","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"java/debugger/impl/src/com/intellij/debugger/impl/attach/SAJDWPRemoteConnection.java","lineNumber":72,"sourceCode":"      String address = mySocketListeningConnector.startListening(arguments);\n      myCommands.set(myCommands.size() - 1, address); // last argument is a port, replace with the real value\n      return address;\n    }\n\n    @Override\n    public VirtualMachine accept(Map<String, ? extends Argument> map) throws IOException, IllegalConnectorArgumentsException {\n      try {\n        GeneralCommandLine commandLine = new GeneralCommandLine(myCommands);\n        if (Registry.is(\"debugger.sa.jdwp.debug\")) {\n          commandLine.getParametersList().replaceOrPrepend(\"-agentlib:jdwp\", \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n\");\n        }\n        startServer(commandLine, false);\n      }\n      catch (IOException e) {\n        throw e;\n      }\n      catch (Exception e) {\n        throw new IOException(\"Unable to start sa-jdwp server\", e);\n      }\n\n      return mySocketListeningConnector.accept(map);\n    }\n\n    @Override\n    public boolean supportsMultipleConnections() {\n      return mySocketListeningConnector.supportsMultipleConnections();\n    }\n\n    @Override\n    public void stopListening(Map<String, ? extends Argument> arguments) throws IOException, IllegalConnectorArgumentsException {\n      mySocketListeningConnector.stopListening(arguments);\n    }\n\n    @Override\n    public String name() {\n      return \"SAJDWPListeningConnector\";","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/JetBrains/intellij-community/blob/be881553f2a76ac8b4ea53950d93f0de78295c19/java/debugger/impl/src/com/intellij/debugger/impl/attach/SAJDWPRemoteConnection.java#L54-L90","documentation":"Thrown by SAJDWPRemoteConnection's custom ListeningConnector.accept when starting the sa-jdwp helper process (an external command built from myCommands, optionally with a debug jdwp agent when Registry key debugger.sa.jdwp.debug is set) fails with a non-IOException exception. The Serviceability Agent-based attach channel cannot be established, so attach aborts.","triggerScenarios":"Calling accept() on the SA JDWP connector: startServer(commandLine, false) throws ExecutionException/InterruptedException or similar non-IOException; the generic catch wraps it as IOException('Unable to start sa-jdwp server'). startServer itself delegates to GeneralCommandLine execution of the sa-jdwp launcher.","commonSituations":"Attaching the debugger to a process via the SA (Serviceability Agent) connector when the helper binary path is wrong, lacks execute permission, or the target process permissions (ptrace scope on Linux) block it; broken JDK install missing SA binaries; macOS SIP blocking SA attach.","solutions":["Verify the JDK used to run the IDE contains the SA tooling (complete JDK install, not trimmed JRE)","On Linux, allow ptrace for the helper: echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope or run the IDE with same-user privileges as the target","Enable Registry key debugger.sa.jdwp.debug to surface the helper process output and inspect its failure","Fall back to a normal socket attach (-agentlib:jdwp) instead of SA-based attach"],"exampleFix":"# before\nsudo sysctl kernel.yama.ptrace_scope=1  # SA attach blocked\n\n# after\nsudo sysctl kernel.yama.ptrace_scope=0","handlingStrategy":"try-catch","validationCode":"// before attach: verify the helper command is executable and target permits SA\nif (!Files.isExecutable(Path.of(helperCommand))) {\n  throw new IOException(\"sa-jdwp helper missing: \" + helperCommand);\n}","typeGuard":null,"tryCatchPattern":"try {\n  VirtualMachine vm = saConnector.accept(map);\n} catch (IOException e) {\n  if (\"Unable to start sa-jdwp server\".equals(e.getMessage())) {\n    // enable Registry 'debugger.sa.jdwp.debug' to capture helper output, or use socket attach\n  }\n}","preventionTips":["Use a full JDK with SA tooling for both IDE and target","Relax ptrace_scope on Linux or attach as the same user","Prefer -agentlib:jdwp socket attach over SA attach in production environments"],"tags":["debugger","attach","serviceability-agent","process"],"backgroundTag":null,"analyzedSha":"be881553f2a76ac8b4ea53950d93f0de78295c19","analyzedAt":"2026-08-14T14:13:06.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}