Debug in IntelliJ with LSP4IJ

Debug Apex without leaving IntelliJ by pairing aer with LSP4IJ, the JetBrains Language Server and Debug Adapter Protocol client. LSP4IJ speaks the same DAP dialect as aer --debug, so you can set breakpoints, inspect locals, and step through code directly inside IntelliJ.

Prerequisites

• IntelliJ IDEA 2024.2 or newer.
• aer 0.0.10+ on your PATH, with any schema/package assets you normally load for local tests.
• LSP4IJ installed from the JetBrains Marketplace (Settings → Plugins → Marketplace → search for LSP4IJ).
• A valid aer license if you plan to debug for longer than the 5‑minute unlicensed session limit.

Create a Debug Adapter configuration

1. Open Run | Edit Configurations… and add a new Debug Adapter Protocol configuration.
2. Give it a name such as Aer Apex Tests.

Server tab

• Choose Command as the server type.
• In the Command field, enter the full aer invocation using absolute paths so the process can find your project assets regardless of IntelliJ’s current directory. A typical setup looks like:

aer test --debug /home/you/projects/salesforce/src

--debug cannot be combined with --watch, but you can keep any --schema, --package, or --db flags you rely on. Leave the connection mode on the default (LSP4IJ streams STDIN/STDOUT to the DAP server that aer starts internally).

Mappings tab

Add the Apex file patterns you want breakpoints for—usually the folders that contain your tests and implementation classes. Common entries include:

• **/*.cls
• **/*.trigger

Configuration tab

• Set the Working directory to the root of your Salesforce project (the folder that contains force-app). LSP4IJ does not change the process working directory, so the fully qualified paths above are still required.
• Leave File blank if you run the entire suite, or point to a specific test class if you prefer to scope the run with --filter.
• Choose Launch as the debug mode.
• Use a minimal launch payload; aer derives everything it needs from the CLI arguments:

{
  "type": "aer",
  "name": "Debug Apex Tests",
  "request": "launch",
  "stopOnEntry": true
}

stopOnEntry is optional; set it only if you want the VM to pause before the first statement.

Run the session

1. Open the Apex test file you care about and set breakpoints (LSP4IJ highlights the gutter when your mapping matches the file).
2. Press Debug on the Aer Apex Tests configuration. aer compiles your project, waits for ConfigurationDone from IntelliJ, and then executes the selected tests.
3. Use IntelliJ’s debugger controls (Step Over, Step Into, Resume) and the Debug tool window to inspect stack frames, locals, and System.debug output.

You can create additional configurations that target narrower slices of work—for example, add --filter OrderServiceTests to the server arguments to focus on one suite.

Tips

• Enable Trace → Verbose on the server tab if you want to watch DAP requests and responses in the Debug Console.
• If the console warns that debugging will terminate after five minutes, register your license with aer license register before retrying.
• Pair this setup with the Interactive Debugging guide for an overview of the DAP features aer exposes.