FEX Core SDK - Troubleshooting Guide

This guide helps you resolve common issues when integrating with FEX Core SDK.

Quick Diagnosis

Symptom Likely Cause Solution
"DLL not found" Missing DLL or dependencies DLL Loading Issues
Error code -20 Invalid license key License Key Problems
Error code -4 Unsupported image format Format-Specific Problems
Error code -6 Cannot open image file Format-Specific Problems
Memory grows over time Buffer not freed Memory/Performance Issues
Slow performance Large image, wrong API Memory/Performance Issues

DLL Loading Issues

"DLL not found" Error

Symptoms:

  • Python: FileNotFoundError: Could not find module 'FEX.Core.dll'
  • C#: DllNotFoundException
  • C++: LoadLibrary returns NULL

Root Causes:

  1. DLL not in expected location
  2. Missing dependencies
  3. Architecture mismatch (32-bit vs 64-bit)

Resolution Steps:

Step 1: Verify DLL location

SDK Directory/
├── bin/
│   └── Win64/
│       ├── FEX.Core.dll          ← Main DLL
│       └── libcrypto-1_1-x64.dll ← Required dependency

Step 2: Check the exact path in your code

import os
dll_path = os.path.join("bin", "Win64", "FEX.Core.dll")
print(f"Looking for DLL at: {os.path.abspath(dll_path)}")
print(f"Exists: {os.path.exists(dll_path)}")

Step 3: Verify dependencies exist

The following files must be in the same directory as FEX.Core.dll:

File Required Purpose
FEX.Core.dll Yes Main SDK DLL
libcrypto-1_1-x64.dll Yes OpenSSL cryptography
sk4d.dll Optional Skia graphics (if SKIA enabled)

Missing Dependency Errors

Symptoms:

  • "The specified module could not be found"
  • "A DLL initialization routine failed"
  • Application crashes on DLL load

Resolution:

  1. Copy all DLLs together:

    bin/Win64/
├── FEX.Core.dll
└── libcrypto-1_1-x64.dll  ← Must be here!

  2. Use Dependency Walker to diagnose:

  3. Add DLL directory to PATH (Python):

    import os
dll_dir = os.path.join(os.path.dirname(__file__), "..", "bin", "Win64")
os.environ["PATH"] = dll_dir + os.pathsep + os.environ["PATH"]

Architecture Mismatch (32-bit vs 64-bit)

Symptoms:

  • "Bad EXE format" error
  • "is not a valid Win32 application"
  • OSError: [WinError 193]

Root Cause: FEX.Core.dll is 64-bit only. Using 32-bit Python/runtime causes this error.

Resolution:

import platform
import sys

# Check Python architecture
arch = platform.architecture()[0]
if arch != "64bit":
    print(f"ERROR: 64-bit Python required. Current: {arch}")
    print(f"Python path: {sys.executable}")
    sys.exit(1)

Fix: Install 64-bit Python from python.org.

License Key Problems

For installation steps and code samples, see License Keys.

Invalid Key Error (Code -20)

Symptoms:

  • InitLibrary() returns RESULT_INVALIDKEY (-20)
  • OpenImage() returns -20 (because the library was never successfully initialised)

Common causes:

  1. FEX_LICENSE_KEY not set in the current shell, or the key was passed to a different process.
  2. Whitespace or line-wrap introduced when copying the key — the value must be a single contiguous string.
  3. Wrong key string — the value isn't the GetData-issued FEX2-… key.
  4. Expired key — the key has passed its expiry date.
  5. Clock skew — the host system clock is far behind or ahead of UTC, which can make a valid key look expired or not-yet-valid.
  6. Wrong working directory (Windows) — the host process's CWD must be the same directory as FEX.Core.dll when InitLibrary is called. The bundled examples handle this automatically; custom integrations that load the DLL from another directory should chdir to the DLL's directory around the InitLibrary call.

Resolution steps:

  1. Confirm the variable is visible to your process.

    # Windows (PowerShell)
$env:FEX_LICENSE_KEY.Substring(0, 5)   # should print 'FEX2-'

    # Linux / macOS
echo "${FEX_LICENSE_KEY:0:5}"          # should print 'FEX2-'

  2. Re-copy the key from your sales email (or secret manager). Make sure no newline, tab, or trailing space was included.

  3. Check the host clock is set to current UTC (within a few minutes).

  4. Try the bundled FexViewer info command with your key — it gives a clear pass/fail without your integration code in the way.

  5. Contact support@getdata.com if the key still fails. Include:

    • The first 4 and last 4 characters of the key (never the full string).
    • The exact error code returned (-20, -21, etc.).
    • SDK version (output of FexViewer info or GetVersionAsJSON).
    • Operating system and architecture.

Expired Key

Symptoms:

  • A key that previously worked now returns -20.
  • Evaluation period has ended.

Resolution:

  • Contact sales@getdata.com for renewal.
  • Check your email for renewal notices.

Memory/Performance Issues

Memory Leaks

Symptoms:

  • Memory usage grows continuously
  • Application slows down over time
  • Eventually crashes with out-of-memory

Root Cause: Not calling FreeAllocatedBuffer() after V2 API calls.

Detection:

import tracemalloc

tracemalloc.start()

# Your code here
for i in range(100):
    buffer = ctypes.c_void_p()
    size = ctypes.c_uint32()
    dll.GetVersionAsJSON(ctypes.byref(buffer), ctypes.byref(size))
    # MISSING: dll.FreeAllocatedBuffer(buffer)

current, peak = tracemalloc.get_traced_memory()
print(f"Memory: {current / 1024 / 1024:.1f} MB")
tracemalloc.stop()

Resolution:

Always use try/finally:

buffer = ctypes.c_void_p()
size = ctypes.c_uint32()
result = dll.SomeFunction_V2(ctypes.byref(buffer), ctypes.byref(size))

if result == 0:
    try:
        # Use buffer
        data = ctypes.string_at(buffer, size.value)
    finally:
        dll.FreeAllocatedBuffer(buffer)  # ALWAYS FREE

Large Image Performance

Symptoms:

  • Opening large images takes minutes
  • File listing is very slow
  • High memory usage

Resolution:

  1. Use V3 API for selective field extraction:

    # Instead of getting all fields
dll.GetFileSystemRecords_V2(...)

# Get only what you need
fields = "Name,Size,Modified"
dll.GetFileSystemRecordsCustom(..., fields.encode(), ...)

  2. Process in batches:

    # Don't load all files into memory at once
batch_size = 1000
for offset in range(0, total_files, batch_size):
    batch = files[offset:offset + batch_size]
    process(batch)

  3. Close images when done:

    # Don't leave images open
image_id = dll.ImageOpen(path, key)
try:
    # ... work with image ...
finally:
    dll.ImageClose(image_id)

Performance Optimization Tips

Issue Solution
Slow image open Use SSD, check image isn't corrupted
Slow file listing Use V3 API with minimal fields
High memory Process in batches, free buffers
Repeated opens Cache image handle, open once

Format-Specific Problems

Error -4: Image Not Supported

Symptoms:

  • ImageOpen() returns -4
  • Certain image files won't open

Root Causes:

  1. Unsupported format
  2. Corrupted image header
  3. Wrong file extension

Supported Formats:

Format Extensions Notes
DD/RAW .dd, .raw, .img, .001 Uncompressed disk image
E01 .E01, .E02, ... EnCase format
L01 .L01, .L02, ... Logical evidence
AFF4 .aff4 If enabled in build

Resolution:

  1. Verify file format:

    import os

path = "evidence/disk.img"
ext = os.path.splitext(path)[1].lower()

supported = {'.dd', '.raw', '.img', '.001', '.e01', '.l01', '.aff4'}
if ext not in supported:
    print(f"Extension '{ext}' may not be supported")

  2. Check file header:

    with open(path, 'rb') as f:
    header = f.read(16)
    print(f"Header bytes: {header.hex()}")

# E01 should start with: 45 56 46 09 0D 0A FF 00
# (EVF signature)

  3. Try opening as raw: If format detection fails, rename to .dd and try as raw image.

Error -6: Could Not Open Image

Symptoms:

  • ImageOpen() returns -6
  • File exists but can't be opened

Root Causes:

  1. File permissions
  2. File locked by another process
  3. Path encoding issues
  4. Network path issues

Resolution:

  1. Check file permissions:

    import os

path = "evidence/disk.E01"
if not os.path.exists(path):
    print("File not found")
elif not os.access(path, os.R_OK):
    print("No read permission")
else:
    print("File accessible")

  2. Check if file is locked:

    • Close other applications that might have the file open
    • EnCase, FTK, or other forensic tools may lock files

  3. Use correct path encoding:

    # For non-ASCII paths
path = "evidence/案件.E01"
encoded_path = path.encode('utf-8')
result = dll.ImageOpen(encoded_path, key)

  4. Avoid network paths if possible:

    • Copy image to local drive for best performance
    • UNC paths may have permission issues

Filesystem-Specific Issues

NTFS Issues:

  • Alternate data streams may not appear in simple listings
  • Very deep paths (>260 chars) may fail on older Windows

FAT32 Issues:

  • 4GB file size limit in original filesystem
  • Timestamps have 2-second resolution

EXT4 Issues:

  • Extended attributes may require additional API calls
  • Some sparse file handling limitations

Debugging Techniques

Enable Verbose Output

import sys

def debug_print(msg):
    print(f"[DEBUG] {msg}", file=sys.stderr)

# Add debug output to your workflow
debug_print(f"Opening image: {path}")
result = dll.ImageOpen(path.encode(), key.encode())
debug_print(f"ImageOpen result: {result}")

Check Error Codes

ERROR_CODES = {
    0: "OK - Success",
    -1: "General error",
    -2: "Buffer too small (V1 API)",
    -3: "File not found",
    -4: "Image format not supported",
    -5: "Image ID not found",
    -6: "Could not open image",
    -20: "Invalid license key"
}

def describe_error(code):
    return ERROR_CODES.get(code, f"Unknown error: {code}")

Diagnostic Tools

Tool Platform Purpose
Dependency Walker Windows Find missing DLLs
Process Monitor Windows Track file access
ldd Linux Check shared library deps
strace Linux Trace system calls

Minimal Test Case

When reporting issues, create a minimal reproduction:

#!/usr/bin/env python3
"""Minimal FEX Core test case"""
import ctypes
import os
import sys

# Configuration
DLL_PATH = "bin/Win64/FEX.Core.dll"
IMAGE_PATH = "sample-data/sample-image.dd"
LICENSE_KEY = "YOUR_KEY"

print(f"Python: {sys.version}")
print(f"Platform: {sys.platform}")
print(f"DLL exists: {os.path.exists(DLL_PATH)}")
print(f"Image exists: {os.path.exists(IMAGE_PATH)}")

try:
    dll = ctypes.CDLL(DLL_PATH)
    print("DLL loaded successfully")

    dll.ImageOpen.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
    dll.ImageOpen.restype = ctypes.c_int

    result = dll.ImageOpen(
        IMAGE_PATH.encode(),
        LICENSE_KEY.encode()
    )
    print(f"ImageOpen result: {result}")

except Exception as e:
    print(f"Error: {type(e).__name__}: {e}")

Support Escalation

Self-Service Resources

  1. Documentation - Check this guide and API references
  2. Sample Code - Review working examples in examples/ folder
  3. Error Codes - See Error Codes Reference

When to Contact Support

Contact support when:

  • Documentation doesn't resolve the issue
  • You've followed all troubleshooting steps
  • You have a reproducible test case
  • License/activation issues

How to Contact Support

Email: support@getdata.com

Include in your report:

  1. SDK Version: (e.g., v1.0.0)
  2. Operating System: (e.g., Windows 11 x64)
  3. Programming Language: (e.g., Python 3.14)
  4. Error Code/Message: (exact text)
  5. Steps to Reproduce: (minimal test case)
  6. Image Format: (e.g., E01, DD)
  7. Log Output: (if available)

Example support request:

Subject: Error -6 opening E01 image

SDK Version: 1.0.0
OS: Windows 11 Pro x64
Language: Python 3.14.0

Problem: ImageOpen returns -6 for specific E01 file

Steps:
1. Downloaded SDK, extracted to C:\FEX-Core-SDK
2. Ran sample: FexViewer.exe info --image sample-image.dd
3. Sample works with sample-image.dd
4. Fails with my E01 file (attached test case)

Error output:
[Attach minimal test case and sanitized output]

Response Times

Priority Response Target
Trial users 2-3 business days
Licensed customers 1 business day
Critical production Same business day

Back to Documentation Index