Troubleshooting and FAQ

How to check profiler agent status?
Which port does the profiler agent use?
I do not see my application in the Monitor Applications list on Welcome screen
Profiled application fails to start: 'Error occurred during initialization of VM. Could not find agent library on the library path or in the local directory: yjpagent'
Enable extended diagnostics to troubleshoot SSH issues
Not enough disk space for temporary files
OutOfMemoryError in the profiler UI
Not enough virtual memory
UI rendering issues on Linux: black, pink, corrupted or improperly repainting window
Wrong icon or font sizes in the profiler UI when using 150% display scale
Large memory snapshot opens slowly
Profiled application crashes capturing memory snapshots

How to check profiler agent status?

The profiler agent status can always be checked by opening the URL https://localhost:<agent port> for a local profiled application or https://<remote host>:<agent port> for a remote profiled application in a web browser. The remote application status can be checked this way if a direct connection was allowed with the help of the agent startup option listen.

By default, the profiler agent uses self-signed SSL certificate, so all modern web browsers like Chrome, FireFox or InternetExplorer will show a security warning, explaining the risks. You can safely accept the risks and proceed further. On the opened page, you should see the version of the profiler agent you have connected to:

YourKit Java Profiler 2024.9-b123

Which port does the profiler agent use?

By default, the profiler agent port is allocated in the range 10001-10010 or a random one is used if all ports in this range are busy. The port can also be specified explicitly with the startup option port. If the profiler agent port is not in the default range 10001-10010, explicitly specify the port in the connection dialog as host:port. Please note that agent port is not one of the ports you may use to communicate with the profiled application or server, like HTTP 8080 or HTTPS 443.

If you are unsure which port is used, look at the profiler agent log. The profiler agent log file is <user home>/.yjp/log/<application name>-<PID>.log, where <user home> corresponds to the account under which the profiled application is started.

I do not see my application in the Monitor Applications list on Welcome screen

If the profiled Java application is missing in Monitor Applications list:

Ensure the application you want to profile is running. Restart the application if has been shut down. If the application fails to start or terminates abnormally, check the application's output, logs etc. for possible errors.
If you run your application and profiler UI on the same machine but under different users, please run an application and UI under the same user or start your application with profiler agent. Java applications running under different user might be missing.
If you profiler remote application with SSH access discovery method, login with the same SSH user under which your application runs or start your application with profiler agent.
If the application is up and running, ensure that the network connection is not blocked by a firewall, an antivirus etc. Check both the remote machine side and the local machine side. The profiler agent port must be allowed.
If you are profiling a remote application, ensure that startup option listen is properly configured. By default, for security reasons the profiler agent binds the socket only to localhost that might resolve to 127.0.0.1. This disables a remote connection to the agent via external network interfaces, but connection is still possible via port forwarding e.g. an SSH tunnel. If you want to allow connections to the remote application via host and port, you should specify the startup option listen=<IP> or listen=all.

Profiled application fails to start: 'Error occurred during initialization of VM. Could not find agent library on the library path or in the local directory: yjpagent'

Ensure that the system requirements are met.
It's important that both the JVM and the profiler agent are compatible in terms of their "bitness" - that is, whether they are 32-bit or 64-bit. Even if you are running a 64-bit operating system, the bitness of the JVM and profiler agent should match.
Another possible reason is that profiler agent library cannot be linked because it depends on other libraries not installed on your system. To see if that is the case, please:
```
cd {profiler directory}/bin/{platform}
ldd libyjpagent.so
```
If ldd shows non-satisfied dependencies, please resolve them by installing the missing shared libraries.
Ensure that you are not using glibc profiler agent on musl system and vice versa.

Enable extended diagnostics to troubleshoot SSH issues

To help YourKit support investigate a network connectivity issue, please enable extended logging by adding -Dyk.ssh.debug=true to <user home>/.yjp/ui.ini. Restart the profiler UI to make the changes effective.

Not enough disk space for temporary files

When the profiler opens a memory snapshot, it may create temporary files in the user's default temporary directory. If there is not enough disk space in the default directory, please specify alternate directory with the help of the property -Dyk.tmp.dir=<directory> in <user home>/.yjp/ui.ini configuration file. Restart the profiler UI to make the changes effective.

OutOfMemoryError in the profiler UI

The profiler UI may run out of memory, e.g. while opening huge snapshots. Huge usually means several gigabytes, but the exact numbers vary in each particular case, depending on snapshot specifics. Please increase the -Xmx in <user home>/.yjp/ui.ini configuration file. Restart the profiler UI to make the changes effective.

Not enough virtual memory

Not enough virtual memory error means that some parts of the snapshot file could not be directly mapped to the virtual memory.

Ensure that the system has enough virtual address space (swap file). Please also ensure you have not set the -Xmx value unnecessarily high.
Try to make snapshots smaller by running your Java application with a lower Java heap limit: -Xmx setting of the profiled application. If the profiled application has a smaller heap, then the resulting snapshots will in general be smaller in size, will take less memory to load, and will allow faster analysis in the UI.

UI rendering issues on Linux: black, pink, corrupted or improperly repainting window

Remote desktop and VNC

You may observe rendering issues like a completely pink or black window, if you use the profiler UI via remote desktop or similar software. In this case, please specify the lines in <user home>/.yjp/ui.ini configuration file:

-Dsun.java2d.xrender=false
-Dsun.java2d.opengl=false

Tiling window managers

There may be rendering issues with a tiling window manager like Sway. Usually it looks like a grey window. If you are using a tiling window manager, please set the environment variable _JAVA_AWT_WM_NONREPARENTING before running the profiler UI:

export _JAVA_AWT_WM_NONREPARENTING=1

Other painting artifacts

We recommend to specify -Dsun.java2d.opengl=false, if you see completely black windows, or you experience painting artifacts in texts. This problem is often caused by the installed video drivers.

Wrong icon or font sizes in the profiler UI when using 150% display scale

YourKit Java Profiler automatically detects appropriate font and icon sizes to match your display properties. However, it may not work properly if 150% display scale is used. If you experience this problem, please specify the following lines in <user home>/.yjp/ui.ini configuration file:

-Dsun.java2d.uiScale=1
-Dyk.font.name=<font name>
-Dyk.font.size=<font size>

Lange memory snapshot opens slowly

Opening a large memory snapshot can sometimes take a lot of time. This is usually because the profiler needs to perform a large number of complex calculations when loading the snapshot. Nevertheless, to speed up the opening of the snapshot, you can use the following solutions:

While loading a snapshot, try to avoid simultaneous running of other applications which use much memory. Running such applications in parallel increases virtual memory swapping which leads to overall system performance degradation.
Consider using a machine with more physical memory (RAM) available.

Profiled application crashes capturing memory snapshots

This problem is mostly a problem of 32-bit JVMs, that have limited virtual memory available (2-4 GB, depending on the OS and virtual memory settings).

Use 64-bit JVM if possible.
Decrease the heap size (-Xmx option) when profiling.
Click Force garbage collection toolbar button several times before capturing a memory snapshot.
Use JVM built-in heap dumper. The dumper produces files in HPROF format, fully supported by YourKit Java Profiler. HPROF dumper is a part of the JVM and requires almost no additional memory resources to make the heap dump.