Troubleshooting

Troubleshooting Guide

Solutions to common issues when using LeanJ.

CLI Issues

CLI Not Found

Error: CLI not found or leanj: command not found

Solutions:

1. Verify CLI is built:

   ls dist/cli/leanj*

2. Add to PATH:

   • See Installation Guide
   • Or use full path: /path/to/leanj <command>

3. Set system property (for IDE):

   -Dleanj.cli.path=C:\path\to\leanj.exe

Controller Not Starting

Error: Controller not running or controller fails to start

Solutions:

1. Check ports are available:

   # Windows
   netstat -ano | findstr :9876
   netstat -ano | findstr :9877
   
   # Linux/macOS
   lsof -i :9876
   lsof -i :9877

2. Use different ports:

   leanj controller start --port 8888

3. Check Java installation:

   java -version

4. Verify controller JAR exists:

   ls dist/controller/controller-1.0.0-SNAPSHOT.jar

5. Run system check:

   leanj doctor

JVM Not Found

Error: No JVMs found or JVM not found

Solutions:

1. List all JVMs:

   leanj jvms

2. Check Java processes:

   jps -l -v

3. Verify JVM is running:

   • Check process list
   • Verify PID is correct

4. Docker JVMs:

   • Ensure agent is configured in Dockerfile
   • Check container is running
   • Verify controller is accessible from container

Attach Failed

Error: Attach failed or Failed to attach agent

Solutions:

1. Run system check:

   leanj doctor

2. Verify tools.jar:

   • Check leanj doctor output
   • Ensure JDK (not just JRE) is installed

3. Check JVM supports attach:

   • Some JVMs don’t support attach API
   • Try with different JVM

4. Verify PID:

   jps -l -v | grep <pid>

5. Check permissions:

   • On Linux, may need same user or sudo
   • Check SELinux/AppArmor restrictions

Controller Issues

Controller Not Receiving Data

Symptoms: No metrics in IDE, empty status

Solutions:

1. Check controller is running:

   leanj status

2. Verify agent is attached:

   leanj status
   # Should show attached JVMs

3. Check controller logs:

   # Windows
   Get-Content logs/profiler-controller.log -Tail 50
   
   # Linux/macOS
   tail -f logs/profiler-controller.log

4. Verify agent configuration:

   • Check VM options include agent
   • Verify controller host/port
   • Check package filter

Port Already in Use

Error: Port already in use or Address already in use

Solutions:

1. Find process using port:

   # Windows
   netstat -ano | findstr :9876
   
   # Linux/macOS
   lsof -i :9876

2. Kill process (if safe):

   # Windows
   taskkill /PID <pid> /F
   
   # Linux/macOS
   kill -9 <pid>

3. Use different ports:

   leanj controller start --port 8888

Agent Issues

Agent Not Connecting

Symptoms: No data from agent, connection errors in logs

Solutions:

1. Check controller host/port:

   # Verify in VM options
   -Dprofiler.controller.host=localhost
   -Dprofiler.controller.port=9876

2. Test network connectivity:

   # From container (if Docker)
   ping controller-host
   curl http://controller-host:9877/api/v1/status

3. Check firewall rules:

   • Ensure ports 9876/9877 are open
   • Check Docker network configuration

4. Verify agent JAR:

   ls dist/agent/agent-core-1.0.0-SNAPSHOT.jar

No Metrics Collected

Symptoms: Agent connected but no metrics visible

Solutions:

1. Check package filter:

   # Verify package matches your code
   -javaagent:agent.jar=package=com.myapp

2. Verify methods are being called:

   • Ensure application is running
   • Check methods match package filter

3. Check flush interval:

   -Dprofiler.flush.interval.ms=1000

4. Review controller logs:

   • Look for incoming snapshots
   • Check for errors

High Overhead

Symptoms: Application performance degraded

Solutions:

1. Increase flush interval:

   -Dprofiler.flush.interval.ms=5000

2. Use CPU timer:

   -Dprofiler.timer=cpu

3. Narrow package filter:

   # Instead of: package=com
   # Use: package=com.myapp.service

4. Profile selectively:

   • Only profile when needed
   • Detach when not profiling

IntelliJ Plugin Issues

CodeVision Not Showing

Symptoms: No inline hints in editor

Solutions:

1. Enable CodeVision:

   • Settings → Editor → Inlay Hints
   • Enable Code Vision
   • Enable LeanJ

2. Check profiling is active:

   • Run → Start LeanJ Profiling
   • Verify status in tool window

3. Refresh IDE:

   • File → Invalidate Caches / Restart
   • Or restart IDE

4. Check agent is attached:

   leanj status

Plugin Not Starting

Error: CLI not found or plugin fails to start

Solutions:

1. Set CLI path:

   -Dleanj.cli.path=C:\path\to\leanj.exe

2. Add CLI to PATH:

   • Restart IDE after adding to PATH

3. Verify CLI works:

   leanj --version

Metrics Not Updating

Symptoms: Metrics are stale or not refreshing

Solutions:

1. Check controller is receiving data:

   leanj status

2. Restart profiling:

   • Run → Start LeanJ Profiling
   • Or detach/reattach agent

3. Check controller logs:

   • Look for broadcast messages
   • Verify IDE connection

4. Refresh IDE:

   • Close and reopen files
   • Or restart IDE

Docker Issues

Container Not Appearing

Symptoms: Docker JVM not in jvms list

Solutions:

1. Check agent configuration:

   ENV JAVA_TOOL_OPTIONS="-javaagent:/agent/agent.jar=package=com.myapp"
   ENV LEANJ_PROJECT=my-service

2. Verify controller accessibility:

   # From container
   curl http://controller-host:9877/api/v1/status

3. Check network:

   • Use host.docker.internal (Docker Desktop)
   • Or shared Docker network
   • Or host IP address

4. Review container logs:

   docker logs <container>

Connection Refused

Error: Connection refused from container

Solutions:

1. Check controller host:

   ENV LEANJ_CONTROLLER_HOST=host.docker.internal

2. Verify controller is running:

   leanj status

3. Test connectivity:

   docker exec <container> ping controller-host

4. Check firewall:

   • Ensure ports are open
   • Check Docker network rules

License Issues

License Validation Failed

Error: License validation failed or Network error

Solutions:

1. Check internet connection:

   ping license-api.leanj.com

2. Verify license key:

   leanj license status

3. Retry validation:

   leanj license validate

4. Check API URL:

   echo $LEANJ_LICENSE_API_URL

Rate Limit Exceeded

Error: Rate limit exceeded

Solutions:

1. Wait a few minutes:

   • License validation is cached for 24 hours
   • Wait before retrying

2. Use cached license:

   • Offline mode uses cached data
   • Check ~/.leanj/license.json

System Health Check

Run comprehensive system check:

leanj doctor

Checks:

• Java installation
• Go installation
• Controller JAR exists
• Agent JAR exists
• Tools.jar availability
• Controller running status
• Port availability

Getting Help

If issues persist:

1. Check logs:

   • Controller: logs/profiler-controller.log
   • IntelliJ: Help → Show Log in Finder

2. Run diagnostics:

   leanj doctor
   leanj status

3. Gather information:

   • Error messages
   • System configuration
   • Steps to reproduce

4. Report issue:

   • GitHub Issues: https://github.com/yyusufaslan/tiny-inline-profiler/issues
   • Include logs and diagnostics

Next Steps

• Review Configuration Guide
• Learn about How It Works
• See CLI Reference