JCuda FAQ - Please read before posting

Note: This FAQ only handles the case of the UnsatisfiedLinkError that often occurs when running programs that involve native libraries. Since version 0.8.0RC of JCuda, the native libraries are contained in JAR files, and are unpacked and loaded automatically when they are required. If you still receive an UnsatisfiedLinkError, please report this in a dedicated thread. Please include information about your operating system and the CUDA version and JCuda version that you are using.

For older versions of JCuda (older than 0.8.0RC), or for other JNI-based libraries, the following may still be helpful:

How to solve an „UnsatisfiedLinkError“

First of all: Make sure that you installed the appropriate Developer driver and the CUDA toolkit for your operating system. You may download the driver and the toolkit at the NVIDIA download site.

When there is a problem with one of the native libraries, an error message will be printed, summarizing some information about the operating system and architecture. Additionally, two stack traces will be printed: The first stack trace refers to the attempt of loading the native library from the JAR file, and the second stack trace refers to the attempt to load the native library as a file.

There are basically four types of an UnsatisfiedLinkError. The exeption Stack Trace contains a more precise error message:

Type 1: UnsatisfiedLinkError: Could not load native library

This is by far the most common error message. Usually, this simply means that a native JCuda library can not be found. Note that this refers to the native library, namely the .DLL files on windows, the .so files on Linux, or the .JNILIB/.DYLIB files on MacOS.

To solve this problem, make sure that these native library files are „visible“ for Java when you try to start the program. In the simplest case, this means that you have to copy all these libraries into the root directory of your project. For example, if you have directories like


C:\Workspace\
**C:\Workspace\Project\**
C:\Workspace\Project\src
C:\Workspace\Project\bin
...

Then you have to copy all the native library files into
*C:\Workspace\Project*

Alternative solution #1

You can explicitly specify the path where Java should look for native libraries. To do this, you can add the following argument to Java when you start the program:
*-Djava.library.path=your\path o he\DLLs*

For example, if you have copied the native libraries into C:\JCudaLibararies, then you can start your program with
java -Djava.library.path=C:\JCudaLibraries\ YourProgram

In Eclipse, you can add this argument under
(Menu) „Run Configurations“ → (Tab) „Arguments“ → (Textbox) „VM Arguments“

Alternative solution #2

A file is also „visible“ when its path is contained in the system-specific environment variable. On Windows, you can add the path where the library files are located to the PATH environment variable. On Linux, you can add the path to the LD_LIBRARY_PATH environment variable.

Type 2: UnsatisfiedLinkError: : Can’t find dependent libraries

When the error message says „Can’t find dependent libraries“, this usually means that you do not have installed the CUDA driver or the CUDA Toolkit. It can also mean that the installed version of the Driver or Toolkit does not match the JCuda version. You can download the CUDA developer drivers and the CUDA toolkit from the NVIDIA CUDA Download Site. Please see the installation notes on this site for further information.

Type 3: UnsatisfiedLinkError: : %1 is not a valid Win32 application
UnsatisfiedLinkError: : **Can’t load IA 32-bit .dll on a AMD 64-bit platform **

This error message may occur on Windows when you are trying to use

  • a 64 bit library on a 32 bit system or
  • a 32 bit library on a 64 bit system
    or when you are trying to start the program with the wrong Java version.

You should first check that you have downloaded the appropriate version for your system. If you already have the right version, make sure that you also have the right version of Java: On a 64 bit Windows, you can use the 32 bit Java Runtime Environment (JRE) for most applications, but you can not use the 32 bit JRE when you want to load a 64 bit native library. When you want to load a 64 bit native library, you also have to use the 64 bit version of the Java Runtime Environment.

Type 4: UnsatisfiedLinkError: : The specified procedure could not be found

This error message usually indicates that the version of the JCuda library and the version of a CUDA library do not match. This may happen, for example, when the CUDA toolkit version is lower than the version that the JCuda DLL was built for. In this case, check again that you are using the JCuda version that matches the version of the CUDA toolikt that you have installed.

Type 5: UnsatisfiedLinkError: : libcuda.so.1: cannot open shared object file: No such file or directory

This error occasionally occurs on Linux systems. The error seems to be caused by something going wrong during the installation of the CUDA toolkit. Various sources suggested that the following should help:

  • create a symbolic link to ‚/usr/lib/libcuda.so.1‘ in ‚/usr/lib/nvidia/libcuda.so.1‘ OR
  • add ‚/usr/lib/nvidia‘ to your ldconfig

If all this does not help, you may do a basic test:

Setting up a minimum JCuda test project

To set up a minimum JCuda project as a basic test, you may follow these steps:

  1. Copy all native JCuda DLL-files or .SO-files and JAR files into one directory, and add the following file as „JCudaRuntimeTest.java“ in the same directory:
import jcuda.*;
import jcuda.runtime.*;
public class JCudaRuntimeTest
{
    public static void main(String args[])
    {
        Pointer pointer = new Pointer();
        JCuda.cudaMalloc(pointer, 4);
        System.out.println("Pointer: "+pointer);
        JCuda.cudaFree(pointer);
    }
}
  1. Then compile the program manually from the Command Line. For Windows this will be

**C:\Test\>****javac -cp ".;jcuda-0.3.2a.jar" JCudaRuntimeTest.java**

For Linux it will be


**/user/Test/>****javac -cp ".:jcuda-0.3.2a.jar" JCudaRuntimeTest.java**

(with a colon : instead of a semicolon ; )
This should create the „JCudaRuntimeTest.class“ file in the same directory.

  1. Start the program with the following command, on Windows:

**C:\Test\>****java -cp ".;jcuda-0.3.2a.jar" JCudaRuntimeTest**

On Linux:


**/user/Test>****java -cp ".:jcuda-0.3.2a.jar" JCudaRuntimeTest**

This should print some information about the pointer which was created in the program. (Note that in both cases no „-Djava.library.path“ should be necessary, because all the native libraries are in the same directory)

If this still does not work, I have no idea what else you could try :wink: But if you intend to ask about this in the Forum, please include the following information:

  • Which operating system / architecture you are using (Windows, Linux, MacOS, 32bit or 64bit)
  • Which driver and toolkit you have installed
  • Which version of JCuda you are using
  • Possibly, your directory structure, command line path, or other information that may be relevant

So far, there is only one FAQ. But 9 out of 10 threads are right about this single question. Later this FAQ may possibly be extended.