Installation Issues

Common Issues

Scenario: I see "-javaagent failed, missing ZIP or bad..." error when starting up

This means that you set up the -javaagent switch properly, but used an incorrect path for contrast.jar. We recommend using a fully qualified path while setting up the switch to prevent any relative path confusion, i.e.:

[joe@localhost /~#] set JAVA_OPTS=$JAVA_OPTS -noverify -javaagent:../contrast.jar 
# Bad! Relative path may be interpreted incorrectly by the launcher.

Using fully-qualified paths fixes everything:

[joe@localhost /~#] set JAVA_OPTS=$JAVA_OPTS -noverify -javaagent:/usr/share/java/lib/contrast.jar 
# Good! Everyone sees this path the same.

If it still fails, double check the path to the contrast.jar file correctly and make sure the user running the server has the correct filesystem privileges to read the file and its parent directory.

Scenario: I don't see Contrast messages in my console at startup

When you start your application server with Contrast, the first thing you should see is a few startup messages from Contrast printed to standard out. There are only a couple reasons this could happen:

The server has not had the JVM options set correctly. The vast majority of the time, this is the issue. Look at the Installation Guide for specific instructions on how to add JVM options to your server startup script or run configuration. Sometimes, users will add Contrast options to the server's startup script which isn't used by their launcher.

The server or application is redirecting standard output. Confirm that Contrast messages are appearing with the rest of the redirected output.

If these steps don't help, consult your application server, IDE or launcher documentation on setting the server's JVM options. The same steps for adding memory (via the -Xmx switch) can be used to add the Java agent.

Scenario: My server doesn't appear on the Contrast site

Are you sure the Engine was installed correctly? Here's a checklist of common fixes for this issue:

  • Did you add the JVM parameters to your container's startup file, run configuration or JAVA_OPTS as was shown in installation documents?
  • Did you add some extra PermGen (-XX:PermGen=128m or more) and heap space (-Xmx768m or more) in case it needs more memory?
  • Did you see the Contrast messages in the console when you started up the server? What about server startup messages?

There are a few network-related reasons why your server wouldn't appear on Contrast's installation wizard, even if Contrast was installed correctly. Assuming you've seen the Contrast and server's startup messages in your console on startup, consider the following options.

Your network requires a HTTP proxy to access Contrast's site If you need to configure an HTTP proxy to reach the Internet in your web browser, it's very likely Contrast will also require an HTTP proxy. To add an one off HTTP proxy, select "Advanced Configuration" and then "Use HTTP Proxy"in the Agent download screen. Fill out values for the HTTP proxy host and port. These values should be supplied by your network administrators. Finally, download and install Contrast as per the normal instructions.

Your network firewall doesn't allow outbound HTTP connections to Contrast's site Work with your network administrators to allow the server on which the Agent is running to create outbound HTTP requests to the Contrast TeamServer from which you obtained said Agent. For SaaS users, this is on port 443.

You're suffering from the Windows and Java7 IPv6 bug Starting with Java 7, the behavior of the IP stack is to utilize IPv6 addresses if available. On Windows, this causes problems with Java machines attempting to make connections out and results in inexplicable "PermissionDenied" exceptions. To fix, this, add to your JVM options.

The Contrast engine ships with a diagnostic tool that can be run by passing the "diagnostic" argument to contrast.jar. This may help you identify your problem area.

$ java -jar contrast.jar diagnostic 
*** Contrast Engine (version 1.X) 
[!] Attempting to connect to the Contrast TeamServer at http://localhost:19080/Contrast (No proxy). 
[+] Looking up http://localhost:19080/Contrast 
        Couldn't resolve host 
[-] Client cannot resolve the Contrast TeamServer. A proxy or DNS change may be needed. 
[+] Issuing HTTP request to Contrast... 
        Executing request... 
        Reading response [200] 
        Response size = 3215 
        Snippet: <!doctype html> <!--[if gt IE 8]><!--> <html class="no-js"> 
[+] Client can connect directly to the Contrast TeamServer. No proxy needed.

You can also customize the diagnostic test and quickly test out different proxy and NTLM configurations by setting the following System properties:

  • - the proxy hostname or IP address.
  • proxy.port - the proxy port (usually 80 or 8080).
  • proxy.auth - one of "none", "basic", "digest" or "ntlm".
  • proxy.user - your proxy user name, if authentication is needed. For NTLM proxies, this is usually DOMAIN\username.
  • proxy.pass - your proxy password, if authentication is needed.
  • contrast.teamserver.url - a different URL than that supplied by the TeamServer at time of download

Scenario: I see OutOfMemoryError, PermGen or other unexplained stack traces

If you're running into unexplained OutOfMemoryErrors, NoClassDefFoundErrors that seem to reference Contrast code or PermGen problems, the following may explain what's happening:

  • You need to add more PermGen (-XX:MaxPermSize=128m or more) and/or heap space (-Xmx768m or more).
  • You're running an unsupported container or version.
  • An unsupported OSGi container within your application is causing class loading issues with Contrast.

If you have enough memory, are running a supported container, and aren't doing any class visibility funkiness, send us some details at

Scenario: I see " Can't promise read/write on cache dir" error when starting up

This means that you don't have read/write access to the cache directory.

The cache directory is located in the contrast directory, and has permissions 755 by default. If the location of the contrast directory has been modified with the contrast.dir property, the cache directory has also moved consequently. You must update the permissions to the cache directory.

NoClassDefFound Error



Causes and Solutions

Agent file name

This error usually indicates you've renamed your agent jar from its original name, contrast.jar. The contrast.jar file name has to match a file that's already inside the jar. (If you unzip contrast.jar, look at the file META-INF/ If it doesn't match, it will cause classloading issues.

The solution: Don't rename the Contrast agent file.

OSGi container

It might also mean that you're using an OSGi container, like Felix or Equinox, that should only use the Java 1.5 agent.

The solution: Only use the Java 1.5 agent, which has the same functionality as the Java agent but doesn't auto-update.

Other solutions

Starting with version 3.5.4, you can try running with -Dcontrast.automaticbootdelegation, which will attempt to supplement classloading behavior to increase the visibility of Contrast agent classes.

OutOfMemory Error

OutOfMemory "PermGen space" Errors

Older versions of Java had separate area for permanent memory use called PermGen. Some of the memory Contrast uses will be kept in this space, but not a lot. If the JVM is already close to its PermGen limit, Contrast may be putting it over.

Adding another 32MB should be more than enough for Contrast.

Other OutOfMemoryErrors

Contrast Protect requires very litle, if any, extra memory. Unless you're already very close to the heap limit, it's possible no additions will be necessary. At the maximum, you should add an extra 128MB. The official minimum required for Contrast is 64MB.

Contrast Assess requires more memory to record the analytics necessary to tell a complete vulnerability story. Contrast suggests using 2x the maximum heap usage during typical Assess usage. The minimum required is 1.75x. (E.g., if you normally run with 128MB of memory, run with 256MB.)

Other Solutions

If you still experience memory problems after adding the necessary memory, or think that Contrast is doing something wrong, send a heap dump. A Contrast team member will gladly take a look!

More Information

How The Java Agent Affects App Performance

AbstractMethod Error



Cause and Solution

If you're experiencing this error on IBM Java 8, your JVM may not include latest FixPack.

Confirm that your JVM includes FixPack17 (FP17), which addresses several bugs, including JIT-related bugs that may lead to this error. If FP17 isn't included, you may try downloading and installing it, or applying the appropriate iFix.