JetBrains/intellij-community · error · IOException

Unable to start sa-jdwp server

Error message

Unable to start sa-jdwp server

What it means

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.

Source

Thrown at java/debugger/impl/src/com/intellij/debugger/impl/attach/SAJDWPRemoteConnection.java:72

      String address = mySocketListeningConnector.startListening(arguments);
      myCommands.set(myCommands.size() - 1, address); // last argument is a port, replace with the real value
      return address;
    }

    @Override
    public VirtualMachine accept(Map<String, ? extends Argument> map) throws IOException, IllegalConnectorArgumentsException {
      try {
        GeneralCommandLine commandLine = new GeneralCommandLine(myCommands);
        if (Registry.is("debugger.sa.jdwp.debug")) {
          commandLine.getParametersList().replaceOrPrepend("-agentlib:jdwp", "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n");
        }
        startServer(commandLine, false);
      }
      catch (IOException e) {
        throw e;
      }
      catch (Exception e) {
        throw new IOException("Unable to start sa-jdwp server", e);
      }

      return mySocketListeningConnector.accept(map);
    }

    @Override
    public boolean supportsMultipleConnections() {
      return mySocketListeningConnector.supportsMultipleConnections();
    }

    @Override
    public void stopListening(Map<String, ? extends Argument> arguments) throws IOException, IllegalConnectorArgumentsException {
      mySocketListeningConnector.stopListening(arguments);
    }

    @Override
    public String name() {
      return "SAJDWPListeningConnector";

View on GitHub (pinned to be881553f2)

Solutions

1. Verify the JDK used to run the IDE contains the SA tooling (complete JDK install, not trimmed JRE)
2. 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
3. Enable Registry key debugger.sa.jdwp.debug to surface the helper process output and inspect its failure
4. Fall back to a normal socket attach (-agentlib:jdwp) instead of SA-based attach

Example fix

# before
sudo sysctl kernel.yama.ptrace_scope=1  # SA attach blocked

# after
sudo sysctl kernel.yama.ptrace_scope=0

// before attach: verify the helper command is executable and target permits SA
if (!Files.isExecutable(Path.of(helperCommand))) {
  throw new IOException("sa-jdwp helper missing: " + helperCommand);
}

try {
  VirtualMachine vm = saConnector.accept(map);
} catch (IOException e) {
  if ("Unable to start sa-jdwp server".equals(e.getMessage())) {
    // enable Registry 'debugger.sa.jdwp.debug' to capture helper output, or use socket attach
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error.unable.to.create.sapidattachingconnector
• ATTACH_VM_FAILED
• Interface method invocation is not supported in JVM {}. Use
• There is no executable code at {0}:{1}
• Cannot construct wrapper object for value of type {}: Unable

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