Table of Contents

• Troubleshooting Approach
• ClassNotFoundException and NoClassDefFoundError
• TypeLoadException and Type Mismatch Errors
• Memory Leaks and OutOfMemoryError
• Thread Deadlocks and Timeouts
• SSL and TLS Handshake Failures
• JVM Startup and Initialization Failures
• Serialization and Marshaling Errors
• Performance Degradation
• Diagnostic Tools Quick Reference
• Frequently Asked Questions

Cross-runtime integration introduces failure modes that don’t exist in single-language applications. When Java and .NET communicate — whether through REST APIs, gRPC, or in-process bridges like JNBridgePro — errors can originate in either runtime, at the boundary between them, or in the configuration that connects them.

This guide covers the most common Java/.NET integration errors, with specific diagnostics and fixes for each.

Need help with a specific integration issue? Contact JNBridge support — our team has 24 years of experience diagnosing cross-runtime problems.

Troubleshooting Approach: Where to Start

Before diving into specific errors, follow this systematic approach:

1. Identify which runtime throws the error — Is it a Java exception wrapped in .NET, a .NET exception, or a bridge/communication error?
2. Check the full stack trace — Cross-runtime stack traces include both Java and .NET frames. The root cause is usually in the innermost exception.
3. Reproduce in isolation — Can you call the Java method directly (without the bridge)? Can you call a simple bridge method? This isolates whether the issue is in Java code, .NET code, or the integration layer.
4. Check versions — Ensure JDK version, .NET version, and bridge version are compatible. Version mismatches cause subtle, hard-to-diagnose issues.

ClassNotFoundException and NoClassDefFoundError

Symptoms:

java.lang.ClassNotFoundException: com.company.MyService
// or
java.lang.NoClassDefFoundError: com/company/MyService

Root causes and fixes:

1. Missing JAR in Classpath

The most common cause. The Java class exists in a JAR file that isn’t on the JVM’s classpath when the bridge loads it.

// Fix: Add the JAR to the classpath configuration
// JNBridgePro: Add to the classpath in your .jnbproperties file
classpath=C:\libs\myapp.jar;C:\libs\dependency.jar

// REST/gRPC: Ensure the JAR is in the service’s classpath
java -cp "myapp.jar:libs/*" com.company.Main

2. Transitive Dependency Missing

Your JAR loads fine, but it depends on another JAR that’s missing.

// Diagnostic: Check what the class needs
jar tf myapp.jar | grep MyService    # Verify class exists
jdeps myapp.jar                       # Show dependencies

// Fix: Add all transitive dependencies
// Maven: mvn dependency:copy-dependencies -DoutputDirectory=./libs
// Gradle: Copy all runtime dependencies to a flat directory

3. ClassNotFoundException vs NoClassDefFoundError

ClassNotFoundException: The class was never found. Check classpath.

NoClassDefFoundError: The class was found during compilation but not at runtime, OR a static initializer failed. Check:

• Static blocks in the Java class — if they throw exceptions, the class becomes permanently unavailable
• Different JDK versions between compile-time and runtime
• JAR file corruption (re-download or rebuild)

TypeLoadException and Type Mismatch Errors

Symptoms:

System.TypeLoadException: Could not load type 'JavaProxy.MyService'
// or
InvalidCastException: Unable to cast object of type 'java.util.HashMap' to 'System.Collections.Generic.Dictionary'

1. Proxy Class Out of Date

The .NET proxy was generated from a different version of the Java class than what’s running.

// Fix: Regenerate proxy classes from the current JAR
// JNBridgePro: Use the Proxy Generation Tool with updated JARs
// After any Java API change, proxy classes MUST be regenerated

2. Java-to-.NET Type Mapping Issues

3. Generic Type Erasure

Java erases generic types at runtime. A List<String> and List<Integer> are both just List at the JVM level.

// Problem: Java method returns List<Customer>, but bridge sees raw List
// Fix: Cast elements individually on .NET side
var customers = javaProxy.GetCustomers()
    .Cast<CustomerProxy>()
    .ToList();

Memory Leaks and OutOfMemoryError

Symptoms:

java.lang.OutOfMemoryError: Java heap space
// or
System.OutOfMemoryException
// or gradual memory growth over hours/days

1. JVM Heap Exhaustion

// Diagnostic: Enable heap usage monitoring
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/tmp/heap-dump.hprof
-Xlog:gc*:file=gc.log:time

// Fix: Increase heap or fix the leak
-Xmx2g    // Increase max heap
// Then analyze the heap dump with Eclipse MAT or VisualVM

2. Cross-Runtime Reference Leaks

When .NET holds references to Java proxy objects, the Java objects can’t be garbage collected. If .NET code creates many Java objects without releasing them, the JVM heap grows until it runs out.

// Problem: Creating Java objects in a loop without cleanup
for (int i = 0; i < 1000000; i++)
{
    var parser = new JavaXmlParser();  // Creates JVM object
    parser.Parse(data);
    // parser reference kept alive by .NET GC
}

// Fix: Dispose or release Java objects explicitly when done
for (int i = 0; i < 1000000; i++)
{
    using var parser = new JavaXmlParser();
    parser.Parse(data);
    // Disposed at end of scope, JVM reference released
}

3. Dual-Runtime Memory Budgeting

// Container with 4GB RAM:
// JVM heap: -Xmx1g (max 1GB)
// CLR heap: System.GC.HeapHardLimit = 1.5GB
// OS + native: 1.5GB
// 
// Common mistake: Setting JVM to 3GB and CLR to 3GB in a 4GB container
// Result: OOM killer terminates the process

Thread Deadlocks and Timeouts

Symptoms:

// Application hangs, no response
// or
System.TimeoutException: The operation has timed out
// or
Thread dump shows BLOCKED threads waiting for locks

1. Cross-Runtime Deadlock

Thread A holds a .NET lock and waits for a Java call. Thread B holds a Java lock and waits for a .NET callback. Neither can proceed.

// Prevention: Avoid calling back into .NET from Java while .NET is calling Java
// Design rule: Bridge calls should be one-directional per operation

// Anti-pattern (deadlock risk):
// .NET calls Java → Java calls back to .NET → .NET calls Java again

// Safe pattern:
// .NET calls Java → Java returns result → .NET processes locally

2. Thread Pool Starvation

// Problem: All .NET thread pool threads blocked waiting for Java bridge calls
// Symptom: ASP.NET Core stops accepting new requests

// Fix: Don’t use async/await with synchronous bridge calls
// BAD:
await Task.Run(() => javaProxy.SlowOperation());  // Consumes thread pool thread

// BETTER: Use a dedicated thread pool for bridge calls
private static readonly SemaphoreSlim _bridgeSemaphore = new(maxCount: 20);
public async Task<Result> CallJava()
{
    await _bridgeSemaphore.WaitAsync();
    try { return await Task.Factory.StartNew(() => javaProxy.Call(), 
          TaskCreationOptions.LongRunning); }
    finally { _bridgeSemaphore.Release(); }
}

3. TCP Timeout Configuration

// JNBridgePro TCP mode: default timeout may be too short for long operations
// Increase timeout in .jnbproperties:
socketTimeout=60000    // 60 seconds (default varies)

// For REST/gRPC: Set appropriate client timeouts
var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };

SSL and TLS Handshake Failures

Symptoms:

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
// or
System.Security.Authentication.AuthenticationException: The remote certificate is invalid

Common Causes and Fixes

Java Keystore Commands

# Import a certificate into Java’s trust store
keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -alias myservice -file myservice.crt

# List certificates in the keystore
keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit

# Verify what TLS versions your JDK supports
java -Djavax.net.debug=ssl:handshake -jar test.jar

JVM Startup and Initialization Failures

Symptoms:

Failed to create Java Virtual Machine
// or
Error occurred during initialization of VM
// or
Could not find or load main class

Common Causes

1. JAVA_HOME not set or wrong version

   # Check which Java is being used
   java -version
   echo $JAVA_HOME    # Linux/Mac
   echo %JAVA_HOME%   # Windows
   
   # Fix: Set JAVA_HOME to the correct JDK
   export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

2. Insufficient memory for JVM

   # Error: Could not reserve enough space for object heap
   # Cause: -Xmx is larger than available RAM
   # Fix: Reduce -Xmx or increase container/system memory
   -Xmx512m    # Start conservative, increase as needed

3. 32-bit vs 64-bit mismatchA 32-bit .NET process can’t load a 64-bit JVM (and vice versa). Ensure both runtimes use the same architecture.

   // .NET: Force 64-bit
   <PlatformTarget>x64</PlatformTarget>
   
   // Verify Java architecture
   java -d64 -version    # Fails if 32-bit

4. JVM already initializedA JVM can only be created once per process. If your code tries to initialize the bridge twice, the second attempt fails.

   // Fix: Use a singleton pattern for bridge initialization
   // See the Connection Pooling section in our Performance Tuning guide

Serialization and Marshaling Errors

JSON Serialization Mismatches (REST/gRPC)

// Java sends: {"firstName": "John"}  (camelCase)
// .NET expects: {"FirstName": "John"} (PascalCase)

// Fix (.NET): Configure case-insensitive deserialization
var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

Date/Time Format Mismatches

// Java sends: "2026-02-20T10:30:00.000+00:00" (ISO 8601 with offset)
// .NET fails: Cannot parse timezone offset format

// Fix: Use DateTimeOffset in .NET, not DateTime
// Or standardize both sides to UTC without offset:
// Java: Instant.now().toString() → "2026-02-20T10:30:00Z"
// .NET: DateTimeOffset.UtcNow.ToString("o")

Null Handling Across Runtimes

// Java: method returns null (reference type)
// .NET: Proxy returns null for reference types, BUT...
// Problem: Java “null Integer” can’t become .NET “int” (value type)

// Fix: Use nullable value types in .NET
int? result = javaProxy.GetCount();  // Can be null
// Or handle in the Java facade:
public int getCountSafe() { return count != null ? count : 0; }

Performance Degradation

See our detailed Performance Tuning Guide for comprehensive optimization. Quick diagnostics:

Diagnostic Tools Quick Reference

Frequently Asked Questions

How do I get a cross-runtime stack trace?

When a Java exception occurs during a bridge call, it’s wrapped in a .NET exception with the full Java stack trace in the inner exception. Check ex.InnerException for the original Java exception class and stack trace. For REST/gRPC, include stack traces in error responses during development (but redact in production).

My integration works locally but fails in Docker. What should I check?

Common Docker-specific issues: (1) JAVA_HOME path differs between local and container. (2) Memory limits — Docker containers have lower memory than development machines. (3) DNS resolution — container networking may not resolve hostnames the same way. (4) File permissions — JAR files may not be readable by the container user.

JNBridgePro proxy generation fails with certain Java classes. Why?

Proxy generation can fail for classes that use unsupported Java features or have complex generics. Common fixes: (1) Ensure the classpath includes all dependencies during proxy generation. (2) Create a facade class that wraps the problematic class with a simpler interface. (3) Contact JNBridge support with the specific error — they may have a workaround.

Can I debug both Java and .NET simultaneously?

Yes. Attach a Java debugger (IntelliJ IDEA or Eclipse with remote debugging: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005) and a .NET debugger (Visual Studio or Rider) to the same process. Set breakpoints on both sides. The bridge call will transfer control between debuggers.

How do I know if an error is in Java, .NET, or the bridge?

Three quick tests: (1) Call the Java method directly from Java — if it fails, the problem is in Java code. (2) Call a trivial bridge method (e.g., javaProxy.ToString()) — if it fails, the bridge is misconfigured. (3) If both work, the problem is in how .NET calls Java — check parameter types, null handling, and thread safety.

Related Articles

• Java .NET Performance Tuning Guide
• Java .NET Integration Security
• Java .NET Integration Testing and CI/CD
• JNBridge TCP Configuration Guide
• How to Call Java from C# — Complete Guide