This guide provides solutions for common issues encountered with AppMap IDE extensions (VS Code, IntelliJ), AppMap Navie, and the AppMap Java agent. It also details how to gather debug logs and prepare a minimal reproducer for reporting bugs.
Symptom: AppMap services fail to start, or you see errors indicating that scanner or appmap binaries are missing or cannot run. Navie may not respond.
Cause: The IDE plugins rely on binary executables (appmap and scanner) to function. These are usually downloaded automatically. In corporate environments with strict firewalls or proxies, this download may fail.
Solution: Manually download the binaries and place them in the correct cache directories.
-
Download Binaries:
- Go to AppMap JS Releases.
- Download the appmap and scanner binaries for your OS and Architecture (e.g., linux-x64, macos-arm64, win-x64.exe).
-
Place Binaries in the Correct Directory:
- Note: Replace <version> with the specific version the plugin is trying to use (check plugin logs if unsure).
- Ensure files have executable permissions on Unix-like systems (chmod +x).
- On Windows, ensure files have the .exe extension.
IntelliJ IDEA:
- Linux: ~/.cache/JetBrains/appland-plugin/
- macOS: ~/Library/Caches/JetBrains/appland-plugin/
- Windows: %LOCALAPPDATA%\JetBrains\appland-plugin\
Directory Structure:.../appland-plugin/
├── appmap/
│ └── <version>/
│ └── appmap-<os>-<arch>
└── scanner/
└── <version>/
└── scanner-<os>-<arch>
VS Code (Plugin Version >= 0.138):- Linux: ~/.cache/appmap/
- macOS: ~/Library/Caches/AppMap/
- Windows: %LOCALAPPDATA%\AppMap\cache\
Directory Structure:.../cache/
├── appmap-<os>-<arch>-<version>
└── scanner-<os>-<arch>-<version>
VS Code (Plugin Version < 0.138):- Location: ~/.appmap (User Home)
Directory Structure:~/.appmap/
├── lib/
│ ├── appmap/
│ │ └── appmap-v<version>
│ └── scanner/
│ └── scanner-v<version>
└── bin/
├── appmap (Symlink or copy of lib/appmap/...)
└── scanner (Symlink or copy of lib/scanner/...)
Symptom: You have successfully recorded a test or run the application, but the new AppMap does not appear in the "AppMaps" sidebar list in your IDE.
Cause:
- Indexer Stuck: Occasionally, the background indexing process may stall.
- Binary Issues: The appmap binary might be missing or failing to run (see section above).
Solution:
- Restart the IDE: This is often the quickest workaround if the indexer process is stuck.
- Check Logs: If a restart doesn't help, check the IDE logs (see "Gathering Debug Logs") for errors related to the scanner process.
Cause: The project may contain extremely large AppMap files (>50MB) or a massive number of small files, overwhelming the indexer.
Solution:
- Delete old or obsolete .appmap.json files.
- Update appmap.yml to exclude "noise". Add libraries, generated code, or utilities that produce massive traces to the exclude list.
Symptom: Tests run and pass, or the application starts normally, but:
- No .appmap.json files are created in tmp/appmap.
- You do not see the message com.appland.appmap.agent.Agent - AppMap agent starting in the console output at startup.
Cause: The AppMap agent JAR is not correctly attached to the JVM. This is the most common reason for missing data.
Solution:
- Verify JVM Arguments: Ensure -javaagent:/path/to/appmap.jar is correctly passed to the JVM.
- Check Agent Order: If using multiple agents (e.g., Jacoco, NewRelic), the AppMap agent should ideally be listed first.
- Maven/Gradle Forking: If running tests, the build tool must fork a new JVM for the agent to attach.
- Maven: Ensure forkCount is set to at least 1 in the Surefire/Failsafe plugin configuration.
- Gradle: Ensure you are not disabling forking (default behavior is usually fine).
Symptom: .appmap.json files are created, but they are empty or contain only metadata with no events.
Cause: The agent is running, but the configuration in appmap.yml does not match the code being executed.
Solution:
- Check the packages list in appmap.yml.
- Common Mistake: Your code is in com.company.project, but the config lists org.example.
- Ensure you are testing the packages you listed.
Symptom: Tests fail with OOM errors when the agent is attached.
Cause: The agent collects runtime data in memory before flushing to disk. This adds overhead.
Solution:
- Increase the max heap size for the test runner.
- Maven: Add -DargLine="-Xmx2g ..."
- Gradle: Configure minHeapSize = "1g" and maxHeapSize = "4g" in your test task.
Symptom: AppMap files are hundreds of MBs in size and slow to open.
Cause: You are instrumenting too much code, often including 3rd party libraries or the JDK itself.
Solution:
- Avoid adding generic packages like java.*, javax.*, or org.springframework.* (root) to your appmap.yml.
- Target only your specific application logic (e.g., com.mycompany.myapp).
If the solutions above do not work, you will need to generate logs to share with support.
- Open the Output panel (Ctrl+Shift+U or Cmd+Shift+U).
- In the dropdown menu (usually top-right of the panel), select AppMap: Services.
- Copy the output. This contains the logs for the indexing service and Navie backend.
- Enable Debug Mode:
- Go to Help > Diagnostic Tools > Debug Log Settings.
- Add appland to the text box and click OK.
- Reproduce the issue.
- Locate Logs:
- Go to Help > Show Log in Explorer/Finder (this opens the directory containing idea.log).
- Primary Log: Open idea.log and search for "appland" or "AppMap".
- RPC Log: Look for a file named appmap-rpc.log in the same directory. This file contains specific details from the AppMap RPC server and is often vital for troubleshooting backend issues.
To get detailed logs from the agent itself (useful for startup issues or missing data), use System Properties.
How to Enable:
Add the following system properties to your JVM arguments (e.g., in your IDE run configuration or command line):
-Dappmap.debug=info,hooks
Where to find the logs:
- Standard Error (Default): By default, logs are printed to stderr (your console/terminal output).
- File Output: If you prefer to write logs to a specific file, add this additional property:
-Dappmap.debug.file=/path/to/agent.log
If you suspect a bug in the AppMap Java Agent (e.g., it causes a crash, deadlock, or valid code to fail), the most efficient way to get it fixed is to provide a Minimal Artificial Reproducer. This is a small, isolated project that demonstrates the bug without involving your proprietary business logic.
Create a project that fails with the AppMap agent attached and passes without it.
Use Spring Initializr (or a plain Java project structure) to generate a fresh project.
- Build Tool: Maven or Gradle (whichever you use).
- Java Version: Match the version you use in production.
Copy only the specific class, method, or library interaction that triggers the issue.
- Example: If the bug happens when serializing a specific Hibernate entity, creates a project with just one entity and one test case that saves/loads it.
- Do not copy your entire database schema or authentication logic.
Add the AppMap plugin to your pom.xml or build.gradle exactly as you have it in your main project.
Create an appmap.yml that targets strictly the isolated code.
name: bug-repro
packages:
- path: com.example.repro
Write a simple test case (JUnit/TestNG) or a Main class that triggers the bug.
- Good: A JUnit test that asserts true but crashes when AppMap is active.
- Good: A curl command sequence if the issue is runtime-request related.
- Run the project without AppMap -> Ensure it PASSES.
- Run the project with AppMap -> Ensure it FAILS.
- Zip the folder (exclude target/, build/, .idea/, .vscode/) or push it to a public GitHub repository.
When submitting this reproducer, include:
- The zipped project or GitHub link.
- The exact command to run (e.g., ./gradlew appmap test).
- The expected behavior vs. actual behavior.
- The agent.log file (with debug enabled) generated during the failure.