NationalSecurityAgency/ghidra · critical · UnsatisfiedLinkError

Z3 libs not found:

Error message

Z3 libs not found: 

What it means

SymZ3.loadZ3Libs() attempts System.load() on libz3 and libz3java native libraries fetched via Application.getOSFile(). If the files are not present in the expected OS-specific directory, an OSFileNotFoundException is caught and re-thrown as UnsatisfiedLinkError. This is the bootstrap step before any Z3 symbolic execution can occur — without these libraries the SymbolicSummaryZ3 extension cannot function.

Source

Thrown at Ghidra/Extensions/SymbolicSummaryZ3/src/main/java/ghidra/pcode/emu/symz3/SymZ3.java:29

 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package ghidra.pcode.emu.symz3;

import ghidra.framework.*;

public class SymZ3 {
	public static void loadZ3Libs() {
		// Load the libraries using a custom search path before the system tries
		String ext = Platform.CURRENT_PLATFORM.getLibraryExtension();
		try {
			System.load(Application.getOSFile("libz3" + ext).getPath());
			System.load(Application.getOSFile("libz3java" + ext).getPath());
		}
		catch (OSFileNotFoundException e) {
			throw new UnsatisfiedLinkError("Z3 libs not found: " + e);
		}
		System.setProperty("z3.skipLibraryLoad", Boolean.toString(true));
	}
}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Download or build Z3 native libraries (libz3.so/libz3.dylib/libz3.dll and libz3java.*) for your platform and place them in the Ghidra OS directory returned by Application.getOSDir().
2. Verify Platform.CURRENT_PLATFORM and the expected library extension match the files you placed (use .so on Linux, .dylib on macOS, .dll on Windows).
3. Reinstall the SymbolicSummaryZ3 extension from a complete distribution that includes native libs for your OS.
4. If building Z3 from source, ensure the Java bindings (libz3java) are built alongside the core library.

// Check for Z3 libs before attempting to load
String ext = Platform.CURRENT_PLATFORM.getLibraryExtension();
try {
    File libz3 = Application.getOSFile("libz3" + ext);
    File libz3java = Application.getOSFile("libz3java" + ext);
    if (!libz3.exists() || !libz3java.exists()) {
        // Inform user to install Z3 native libs for this platform
    }
} catch (OSFileNotFoundException e) {
    // libs missing — guide user to install before using SymZ3 features
}

try {
    SymZ3.loadZ3Libs();
} catch (UnsatisfiedLinkError e) {
    if (e.getMessage().startsWith("Z3 libs not found")) {
        // Notify: install Z3 native libs for platform X
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling SymZ3.loadZ3Libs() when Application.getOSFile("libz3" + ext) or Application.getOSFile("libz3java" + ext) throws OSFileNotFoundException — i.e., the Z3 native libraries for the current platform are not installed in the Ghidra OS directory.

Common situations: The SymbolicSummaryZ3 extension was installed but the Z3 native binaries for the running platform were not bundled or downloaded; running on an OS/architecture (e.g., ARM Linux) for which prebuilt Z3 libs aren't shipped; the extension's OS directory structure is incomplete after a manual install; a Ghidra upgrade reset the extension directory without re-adding the native libs.

Related errors

• Emulation requires a Sleigh language
• This mapper cannot handle Harvard guests
• Trace is not opened in this tool
• There is no platform
• Given platform is not from the current trace

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/d4e20c2f094c6a34. Report an issue: GitHub.