Skip to main content
Sign in

Resolve ClassNotFoundException errors in JavaScript index stages

  • Updated

Issue

JavaScript index pipeline stages fail with errors similar to the following when attempting to reference Java classes:

java.lang.ClassNotFoundException: com.microsoft.sqlserver.jdbc.SQLServerDriver

or:

java.lang.ClassNotFoundException: com.hierynomus.msdtyp.AccessMask

These errors commonly occur when migrating custom JavaScript stages from Fusion 4 to Fusion 5 and attempting to use external Java libraries such as JDBC drivers or third-party SDKs.

 

Diagnosis

The issue is confirmed if:

  • The JavaScript stage references Java classes using Java.type or direct class imports.

  • The required JAR file has been uploaded to Fusion blob storage.

  • The class remains unavailable at runtime inside the indexing service.

  • Other components, such as JDBC data sources, function correctly using the same driver.

You can validate the error by reviewing indexing service logs:

kubectl logs deployment/indexing -n <fusion-namespace>

Look for ClassNotFoundException entries referencing the missing class.

 

Environment

Fusion 5.x (self-hosted)
Kubernetes deployments (for example, Amazon EKS, AKS, GKE)
Index pipelines using JavaScript stages
External Java libraries such as JDBC drivers or SMB libraries

 

Cause

Fusion 5 is deployed as containerized microservices running in Kubernetes. Each service runs within its own isolated classloader and container runtime.

Uploading a JAR file to Fusion blob storage does not automatically add that library to the indexing service classpath. Blob storage is not part of the JVM runtime classpath used by the indexing microservice.

JavaScript stages execute inside the indexing service container. That runtime does not automatically discover or load arbitrary external JAR files unless they are explicitly included in the container’s classpath at startup.

As a result, JavaScript stages cannot resolve classes that are not bundled with the indexing service image or explicitly mounted and configured.

 

Resolution

Option 1: Replace custom JDBC logic with the JDBC lookup stage

If the JavaScript stage is used to create JDBC connections and execute SQL queries, use the built-in JDBC lookup stage instead.

The JDBC lookup stage:

  • Manages driver loading internally

  • Uses configured JDBC data sources

  • Avoids custom driver instantiation in JavaScript

  • Is fully supported in Fusion 5 index pipelines

To implement:

  • Create or verify a JDBC data source in Fusion.

  • Add a JDBC lookup stage to the index pipeline.

  • Configure the SQL query and field mappings directly in the stage UI.

This approach removes the need to manually instantiate the driver in JavaScript, such as:

var Driver = com.microsoft.sqlserver.jdbc.SQLServerDriver;

Using the JDBC lookup stage is the recommended approach for relational database enrichment.

Option 2: Attempt JAR injection into the indexing service

If no built-in stage exists for the required functionality, you can attempt to mount the required JAR into the indexing deployment.

This involves:

  • Creating a Kubernetes volume containing the required JAR.

  • Mounting the volume into the indexing pod.

  • Modifying the container configuration so the JAR is included in the JVM classpath.

Example deployment inspection:

kubectl get deploy indexing -n <fusion-namespace> -o yaml

 

However, even with JAR injection, classloading may still fail if:

  • The indexing service initializes its classloader before the mounted path is included.

  • The runtime does not dynamically reload additional libraries.

JAR injection is not guaranteed to work for JavaScript stages and is not considered a long-term solution.

Option 3: Develop a custom Java index stage

For advanced integrations such as SMB libraries or other external SDKs, the recommended long-term solution is to implement a custom Java index stage using the Fusion Index Stage SDK.

A custom Java stage:

  • Is compiled with required dependencies bundled

  • Ensures all required libraries are on the classpath

  • Avoids JavaScript runtime classloading limitations

  • Provides full control over external integrations

To begin:

  • Use the Fusion Index Stage SDK.

  • Package required third-party libraries as part of the stage build.

  • Deploy the custom stage according to the SDK documentation.

  • Register the stage in Fusion and add it to the index pipeline.

This approach ensures consistent behavior across environments and avoids runtime classloader conflicts.

 

Summary

ClassNotFoundException errors in JavaScript index stages in Fusion 5 are typically caused by classloader isolation within containerized microservices.

Uploading JAR files to blob storage does not make them available to the indexing runtime.

Recommended approaches:

  • Use built-in stages such as JDBC lookup whenever possible.

  • Avoid relying on JavaScript stages for complex external integrations.

  • Implement a custom Java index stage when external libraries must be used.

These methods align with Fusion 5’s microservices architecture and ensure reliable, maintainable index pipeline behavior.

Powered by Zendesk