General FAQ

In addition, there are other sections available, which may also be of use:



My application cannot access Network Drives when it runs as a Windows Service.

By default, Windows Services run as the SYSTEM user. The problem is that the SYSTEM user does not have access to Network Resources. If your application is working fine when it runs as a Windows Service, then the first thing to try is running your service as the user you were logged in as when running it as a console application.

To do this,

The service will now be running under the same environment as it was being run as a console application, so everything should now be working correctly.

Depending on your security requirements, you may wish to create and configure a new user especially for the service.

On some systems, drives mapped to a drive letter (alphabet indicating a drive) are not always accessible on system restart until a real user actually logs on and connects to the drive. The workaround is to use the UNC syntax (full path including a machine name) to reference the drive directly rather than using the mapped drive letter.

Example: UNC syntax (full path including a machine name)

The JVM exits unexpectedly when requesting a thread dump.

When I request a thread dump by pressing CTRL-BREAK, CTRL-\, or via the API, I get the following message in the log and the JVM is restarted:

Log Message:
wrapper  | JVM exited unexpectedly.

Please make sure that you have not specified the -Xrs flag when launching the JVM. This flag is useful in some environments when using Java without the Wrapper, but it compromises the Wrapper's ability to respond to the various system signals.

To tell the Wrapper and thus its JVM to ignore system signals, use the wrapper.ignore_signals property instead. Make sure you have read the documentation first.

My application uses the Windows COM API, but it doesn't work with the Wrapper.

Some users have reported problems when attempting to get their COM applications working with the Wrapper. The application will work fine as a standalone independently, but when run under the Wrapper errors like the following are thrown:

Error Message:
Caught java.lang.NullPointerException: name can't be null while loading driver com.sun.comm.Win32Driver

The COM API requires two files to be available. The win32com.dll file on the library path, and a file located in a lib subdirectory of the directory returned by System.getProperty("java.home").

Problems are caused if your wrapper.conf has configured that you use a different JVM than is specified by your JAVA_HOME environment variable. You can make sure you are using the correct JVM by specifying the following property in your wrapper.conf file.

Example of "wrapper.conf" file:

My application is throwing security exceptions when I run with the Wrapper.

The only difference between the way your application is running under the Wrapper and the way is was running before being integrated is that before your application's main method was being called directly by the JVM on startup. Now, assuming that you are using the WrapperSimpleApp or WrapperStartStopApp helper classes, the JVM first calls that class's main method, then after the Wrapper has initialized, it calls your application's main method.

This can cause some problems when a Security Manager is in use. The reason is that the Java security manager searches up the call stack to make sure that every class and method is authorized to call the protected code before granting access. If the Wrapper's classes exist in your call stack and they are not given privileges, then you will get a security exception.

Try giving wrapper.jar permissions by adding the following to your policy file. This usually fixes this kind of problem.

policy file:
// Give Wrapper classes full permissions
grant codeBase "file:../lib/wrapper.jar" {

Does the Wrapper handle the problem of JVMs exiting when a user logs out under Windows?

Some Java Service applications have a problem with the Java process exiting whenever a user logs out under Windows. Wrapper has handled this correctly since its first release.

The Java side of the Wrapper requires a native library: Windows: wrapper.dll, Linux/UNIX: to make this work. The native library is responsible for trapping all system signals sent to the JVM process and handling them correctly. A Java Application may handle these signals by implementing the controlEvent method in the WrapperListener interface.

If you are experiencing any problems with your JVM being restarted by the Wrapper when a user logs out, please verify that the library is being loaded. If it is not, then a warning message will be displayed in the JVM output during the WrapperManager initialization.

You can find examples of what happens when the user logs out while the Wrapper is being run as a console application and as a service in the Examples section of the documentation.

How can I change the priority at which my application runs on the system?

On Windows systems, the priority can be set by setting the wrapper.ntservice.process_priority property in the wrapper.conf file. Please visit the Configuration Overview for more details.

On UNIX systems, the suggested method for setting the priority is to use the "nice" command in your shell scripts when launching the Wrapper. The example scripts shipped with the Wrapper show how to do this. See "man nice" or "info nice" for details about how to use "nice".

How can I change the user directory of my application?

By default, the Wrapper sets the JVM's user directory to the location of either the wrapper.exe file on Windows or Wrapper shell script on UNIX systems. This is done to make it possible to reliably make use of relative paths within your application. Normally this would not be possible because the user directory would depend on where the JVM was launched from.

Relative paths make it extremely easy to install an application as it can usually be unzipped into any directory and run reliably.

There are some cases where it is necessary to set the user directory to a location other than the default. This is done by setting the wrapper.working.dir property.


Important - Make sure that you have read over the documentation for the working directory property before playing with it. You will safe yourself some headaches.

I have several Wrapper's and JVMs running. How can I tell which is which in the Windows Task Manager.

When running several copies of the Wrapper under Windows, it is not easy to tell which application is which in the Task Manager because they all show up as wrapper.exe and java.exe. It is not possible for the Wrapper to implement a feature to change this name because Windows does not allow that for security reasons.

The workaround is a bit of a hack, but it works great.

  • Rename the wrapper.exe file to wrapper-myapp.exe.
  • Then modify the batch files so they use this new wrapper-myapp.exe.
  • For the Java process, you have to do the same thing. Go into the %JAVA_HOME%/bin directory and simply copy java.exe to java-myapp.exe.
  • Then modify the wrapper.conf file so that new java-myapp.exe is used.

Now when you look at your Windows Task Manager, it will be easy to tell which exe is which.

Note, you can also set the wrapper.pidfile and properties in the wrapper.conf file. These will create files containing the pids. These pids can then be compared with those shown in the Task Manager. Note that you need to configure the Task Manager to display process pids.

How do I run the Wrapper as a specific user?

On Windows, this is done by setting the wrapper.ntservice.account property. Be sure to read the documentation fully and then reinstall the service.

On UNIX, this is done by setting the RUN_AS_USER variable in the Wrapper shell script src/bin/ (on older Wrapper versions, this file was named ''). When running with the console command, the Wrapper will run as the current user. However, when run with the start command, it will change to the specified user and then launch the Wrapper. This means that the current user needs to have permission to change users.

How can I monitor my Java application running as Windows Service with VisualVM?

If a Java application is running as Windows Service, it's actually not running in the same context/session as the user launching VisualVM. Therefore VisualVM is not able to find the Java application by default.

Until Windows XP, the lax security policy for Windows Services actually made it possible to solve this quite easily with the following steps:

At the time a JVM is starting, the JVM is writing its process and hook information to the location specified by the environment variable %TMP%. Please bear in mind that some environment variables (including this one) are defined differently for each user. So the contexts where your service and VisualVM are running must use the same value for this environment variable.

Please set the environment variable "TMP" for the Wrapper process in your Wrapper Configuration file:

After doing so, please (re)start the service. Now start a console and set the TMP environment variable to the same value you specified in the configuration file:

set TMP=C:\tmp
C:\Program Files\...\jvisualvm.exe

VisualVM should now be able to list the Java process.

While the above is working for Windows versions until Windows XP, Windows Vista/7 (and later) will most likely not allow that anymore due to stricter security measurements. So the only way to resolve this is to use the JMX Remote Monitoring settings (this requires at least Java 1.5).

Please set this properties in your Wrapper Configuration file:

Please use unused numbers for 'N' with the<n> property and replace 'XXXX' with a unused port number on your machine. From VisualVM, please select "File"-> "Add JMX Connection". In the "Connection" field please input "localhost:XXXX" (XXXX is the port you assigned in the conf file).


For more information about JMX Monitoring & Management, please also have a look at our JMX Control site or also visit the documentation by Oracle.

How can I set a fixed MAC address on virtual machines?

In some environments where virtual machines are deleted and created constantly with automation tools, the Wrapper will stop working as soon as the HostId (which is based on the MAC address) is different than the one set in the server license key. In that case, the owner of the license should reset manually the license key which breaks the autonomous process to create virtual machines. Depending of the virtualization tool that your are using, it is possible to set a fixed MAC address to virtual machines. By always using the same MAC address, you are guaranteed that the Wrapper will start without license key errors.

Please consult the following documentation: