Troubleshoot the Java microagent

This is a non-exhaustive list of troubleshooting strategies. If you need help, please email us at or contact us through our web chat.

Diagnosis tool

As of version 0.4.19, the Sqreen microagent for Java includes a command-line tool to check common setup issues. This tool works with Linux, but does not work on Windows.

Use the following command to diagnose issues.

java -jar sqreen.jar <command>
<command> Output
version show the version of microagent
status display the status of all running JVMs
status <pid> display the status for JVMs whose PID is <pid>
log-archive create an archive of all running Sqreen microagent logs
debug-log-archive <d> create an archive of all running Sqreen microagent logs with log level set to DEBUG; <d> = specify time to log in seconds

Contact Sqreen support

When contacting Sqreen support, please provide the following information for faster diagnosis:

  • type and version of the web application server (if any)
  • type and version of database server (if any)
  • Sqreen microagent log with log_level=DEBUG (see Diagnosis tool above)
  • list of your application dependencies from your pom.xml, build.gradle, or build.xml file
  • output of the command java -jar sqreen.jar status (see Diagnosis tool above)

Require Sqreen first

Problem: Many issues stem from the same root cause: the Sqreen microagent is not first in your application.

If the Sqreen microagent does not execute first in your application, the microagent cannot instrument the modules/agents that exist before it. Symptoms of this problem include:

  • The database driver is not protected by Sqreen logic.
  • The request context lost; the microagent cannot be determine which HTTP request the code relates to.

Solution: Ensure that the Sqreen microagent executes first in your application. If you use an Application Performance Monitoring agent or any other agent on the JVM, ensure the Sqreen microagent is the last agent in the command line.

Deprecated application tokens

Problem: There is a problem with my application token.

Solution: Sqreen microagents used to use application tokens. These tokens were unique to an application. Sqreen has deprecated application tokens.

Sqreen now uses organization tokens. These tokens are available throughout the organization to which your account belongs.

While Sqreen continues to support application tokens for backward compatibility in the short term, we encourage you to convert your applications to use organization tokens.

Expired tokens

Problem: My organization token is not working. The error message reads 401 Unauthorized.

Solution: If your Sqreen plan expires, the microagent and the organization tokens remain in your app, but the microagent cannot authenticate with the Sqreen Platform anymore.

To resolve the issue, you can uninstall the Sqreen microagent from your app, or you can contact Sqreen to renew your plan subsciption. With a renewed subscription, your microagent will be able to authenticate with the Sqreen Platform using the same organization tokens.

Sqreen does not start up

Problem: Sqreen is not starting up properly.

Solution: Be sure to pass the -javaagent parameter to the JVM before the -jar parameter. Check the parameters provided to the Java process:

ps -ef | grep java

The resulting line should include the -javaagent: parameter with the path to the Sqreen microagent's JAR file. If not, the application startup file is incorrect.

If you change this parameter, restart the JVM for the changes to take effect.

Microagent does not write to log file

Problem: The Sqreen microagent does not create or write to a log file.

Solution: By default, the Sqreen microagent records logs in the /tmp/sqreen.log file. The microagent creates a log file when it starts. If it cannot write to the log file, proceed with the following checks.

  • Check the log location you configured (see Configure the Java microagent documentation).
  • Check that the JVM process has the right to write to the log file.
  • By default, the microagent writes its log to the file system in /tmp/sqreen.log but this does not work well with Heroku apps because log files are lost on each deployment/restart. Set the following environment variable to configure the microagent to write logs to standard output: SQREEN_LOG_LOCATION=/dev/stdout. Redeploy your Heroku application.

If the problem persists, change the log_level parameter to DEBUG and prepare a microagent log with log_level=DEBUG, then contact Sqreen support for assistance.

-Dsqreen.log_level='DEBUG' -Dsqreen.log_location=/tmp/sqreen.log

Web application server issues

Problem: There seem to be issues with the Sqreen microagent and my web application server.

Solution: Check the web app server's logs for any unexpected errors during startup or while executing requests. Some errors report JVM arguments, and include the -javaagent parameter.

Error messages about SSL/TLS and encryption

Problem: Error messages about SSL/TLS and encryption in the microagent logs.

Solution: Refer to Configure the Java microagent for details.

No monitored HTTP requests on Sqreen

Problem: The Sqreen microagent does not appear to be monitoring HTTP requests.

Solution: Check the traffic to your application. The Sqreen microagent passively monitors your app so your app must receive traffic for Sqreen to monitor.

Nothing in the DB requests field

Problem: Sqreen does not show anything in the DB requests field.


  • Check to see if your database is compatible with the Sqreen microagent.
  • Confirm that a data protection plugin is enabled.

If the problem persists, contact Sqreen support for assistance.

Microagent is slow to instrument

Problem: The Sqreen microagent builds a list of all the relevant classes that it must instrument in your app. While this process is usually very fast, there are some known cases where it can cause performance issues, such as when the app uses large libraries with signed packages.

Solution: Use the ignored_packages_prefixes property to get the Sqreen microagent to ignore specific classes. This property must contain a comma-separated list of class names and packages to ignore. Refer to Configure the Java microagent for further details.