Supermaven Extension Crashing JetBrains IDE on Startup: Fix It

May 19, 2026 · Editorial Team · 6 min read · supermaven troubleshooting error-fix

You installed the Supermaven plugin for IntelliJ IDEA, WebStorm, or PyCharm, restarted the IDE as instructed, and now the IDE crashes before it even finishes loading. Or maybe it loads but freezes for 30-60 seconds every time you open a file, and the Activity Monitor or Task Manager shows the JVM pinning a core. In some cases the IDE opens but the Supermaven plugin shows an error icon with no useful message, and completions never appear. All of these are variants of the same underlying problem: the Supermaven binary agent process isn't starting correctly, or it's starting and then consuming resources in a way the JVM can't handle gracefully.

What this error actually means

Supermaven's JetBrains plugin works differently from most JetBrains plugins. Instead of running purely as Java code inside the JVM, it launches a native binary process called the Supermaven Agent, written in Rust, which handles the actual completion logic. The plugin communicates with this agent over a local IPC socket. When the agent fails to start, the plugin can hang waiting for the socket connection, which blocks the IDE initialization thread and causes either a startup freeze or a crash.

JetBrains IDEs log crashes and freeze details to platform-specific log directories. The crash report contains the actual exception or native signal that caused the problem. Without reading the crash log, you're guessing.

Quick fix (when you need it working in 60 seconds)

Start the IDE from the command line so you see the startup output:
- macOS: /Applications/IntelliJ\ IDEA.app/Contents/MacOS/idea
- Linux: /path/to/idea.sh
- Windows: idea64.exe from the bin directory Look for Supermaven-related lines in the terminal output.
Open the IDE log before the crash happens (if you can): Help > Show Log in Finder/Explorer. The idea.log file shows what happened right before the crash.
Disable Supermaven before launching: on macOS, hold Shift during launch to open the plugin management screen and disable Supermaven.
If the IDE loads with Supermaven disabled, the crash is definitely plugin-caused. Proceed to the full diagnosis below.
Update Supermaven to the latest version through the JetBrains Marketplace before trying anything else.

Why this happens

The native agent binary is the most common crash cause. Supermaven ships platform-specific binaries inside the plugin JAR. When the plugin is installed, it extracts the appropriate binary to ~/.supermaven/ and makes it executable. If this extraction fails (due to disk permissions, disk space, or a corrupted JAR), the plugin tries to launch a binary that doesn't exist or isn't executable. The plugin's timeout handler then crashes the initialization.

JVM memory limits are a second major cause. JetBrains IDEs have a configurable heap size, set in the *.vmoptions file for each IDE. The default is often 2048m for newer IDEs. When Supermaven's agent starts and establishes its IPC connection, there's a brief period where memory usage spikes. If the JVM heap is already near its limit from loading a large project (common in monorepos or large Java projects), this spike triggers garbage collection that delays the Supermaven IPC handshake past its timeout. The plugin sees the timeout as a crash.

macOS Gatekeeper is a reliable culprit. The Supermaven agent binary is downloaded as part of the plugin JAR, which JetBrains signs and validates. But the extracted native binary itself isn't necessarily individually signed or notarized. When the plugin tries to execute it, Gatekeeper may block it without showing an obvious error to the IDE user. The IDE just hangs waiting for a process that never starts.

Plugin conflicts in JetBrains IDEs can cause startup crashes when two plugins compete for the same listener or service initialization order. If you have another AI completion plugin (like GitHub Copilot for JetBrains, or JetBrains AI Assistant), both might try to initialize at the same time during startup and one wins while the other crashes.

IDE version incompatibility is a straightforward cause that's easy to overlook. JetBrains IDEs are versioned by year and patch (2025.3.2, 2026.1.1, etc.), and plugins declare which IDE API versions they support. If you've updated to 2026.1 and the current Supermaven build only declares compatibility through 2025.3, JetBrains will still install it (with a warning), but API changes between major versions can cause runtime crashes.

Permanent fix

Read the crash log first. On macOS, open ~/Library/Logs/JetBrains/{IDE name}/idea.log. On Linux: ~/.cache/JetBrains/{IDE}/log/idea.log. On Windows: %APPDATA%\JetBrains\{IDE}\log\idea.log. Search for "Supermaven" or "Exception" to find the relevant section.
Clear the Supermaven agent and let it re-extract:
```
rm -rf ~/.supermaven/
```
Then restart the IDE. Supermaven will re-extract the binary fresh from the plugin JAR.
On macOS, remove the quarantine flag from the agent binary after extraction:
```
xattr -dr com.apple.quarantine ~/.supermaven/
```
You may need to run this after the first IDE launch so the binary exists to have the flag removed.
Increase the IDE heap size. Edit the .vmoptions file (Help > Edit Custom VM Options) and increase the max heap:
```
-Xms512m
-Xmx4096m
```
4 GB gives enough headroom for the Supermaven initialization spike.
Check for plugin conflicts. Disable other AI completion plugins:
- Settings > Plugins > Installed
- Disable GitHub Copilot, JetBrains AI Assistant, or Tabnine
- Restart and see if Supermaven works alone
Verify IDE version compatibility. Open the Supermaven plugin page in the JetBrains Marketplace and check the "Compatible with" field. If your IDE version isn't listed, you need to either update the plugin (if an update exists for your IDE version) or roll back the IDE.
For Linux systems, check that the agent binary has execute permission after extraction:
```
ls -la ~/.supermaven/
chmod +x ~/.supermaven/supermaven-agent
```
If you're on a corporate machine with security software, add ~/.supermaven/ to the exclusion list of your EDR or antivirus. Security tools that scan executables on launch can hold the binary long enough to trigger Supermaven's startup timeout.

Prevention

Before updating JetBrains IDE, check the Supermaven plugin page for compatibility. One minute of checking saves you from a broken setup that might not have a same-day fix if the plugin hasn't been updated yet for the new IDE version.

Keep an eye on your IDE heap usage. JetBrains IDEs show heap usage in the status bar if you enable it (View > Appearance > Status Bar Widgets > Memory Indicator). If you're regularly using 80%+ of heap before Supermaven even loads, increase the heap proactively.

Run IDEs from the command line when debugging. The terminal output gives you information that the IDE's startup splash screen hides, and it lets you see whether the agent binary is launching or not before the crash happens.

For teams with corporate security policies, document the process of adding the ~/.supermaven/ directory to AV exclusions in your developer onboarding guide. This prevents every new team member from hitting the same startup hang.

When the fix doesn't work

If the IDE still crashes with Supermaven enabled after all the above steps, collect the following before contacting support:

The crash log section covering the Supermaven initialization (from idea.log)
Your JetBrains IDE version (Help > About)
Supermaven plugin version (Settings > Plugins)
Output of ls -la ~/.supermaven/
macOS: output of spctl --assess --verbose ~/.supermaven/supermaven-agent

File an issue at github.com/supermaven/supermaven with this information. The Supermaven team has historically been quick to address startup crashes since they affect the very first experience with the tool.

For urgent situations where you need your IDE working immediately, disable Supermaven and use GitHub Copilot for JetBrains or JetBrains AI Assistant as a temporary replacement while waiting for a fix. Both have reliable JetBrains integration that doesn't depend on native subprocess execution.