What causes Fabric Copy Activity Error 20002?

The _JAVA_OPTIONS system environment variable contains invalid arguments or a maximum heap size (-Xmx) that exceeds the available physical memory on the gateway machine. Conflicting JVM options set across multiple environment variables (e.g., _JAVA_OPTIONS, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS) that together produce illegal argument combinations. A previous administrator set global JVM flags for a different application that are incompatible with the gateway's JVM requirements. The gateway was not restarted after changes to JVM-related environment variables, so the old invalid configuration is still active

How do I fix Fabric Copy Activity Error 20002?

Step 1: Log in to each node of the on-premises data gateway cluster and open System Properties → Advanced → Environment Variables.. Step 2: Locate the _JAVA_OPTIONS system variable (and any related variables such as JAVA_TOOL_OPTIONS) and review the values for illegal flags or heap size settings larger than the machine's available RAM.. Step 3: Set _JAVA_OPTIONS to a safe value such as '-Xms256m -Xmx8g' (or up to -Xmx16g if the machine has sufficient RAM); remove any unknown or application-specific flags that were not intentionally set for the gateway.. Step 4: Save the changes and restart the on-premises data gateway service on every node in the cluster.. Step 5: Rerun the pipeline and verify the copy activity completes; if the error persists, temporarily clear _JAVA_OPTIONS entirely to isolate whether the variable is the root cause.

High severitygatewayMicrosoft Fabric →

Power BI Refresh Error:
Fabric Copy Activity Error 20002

What does this error mean?

The on-premises data gateway failed to invoke the Java Native Interface (JNI), typically because illegal or oversized JVM arguments are set in the system environment, preventing JVM creation. This causes copy activities requiring Java (Parquet, ORC) to fail.

Common causes

1The _JAVA_OPTIONS system environment variable contains invalid arguments or a maximum heap size (-Xmx) that exceeds the available physical memory on the gateway machine
2Conflicting JVM options set across multiple environment variables (e.g., _JAVA_OPTIONS, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS) that together produce illegal argument combinations
3A previous administrator set global JVM flags for a different application that are incompatible with the gateway's JVM requirements
4The gateway was not restarted after changes to JVM-related environment variables, so the old invalid configuration is still active

How to fix it

1Step 1: Log in to each node of the on-premises data gateway cluster and open System Properties → Advanced → Environment Variables.
2Step 2: Locate the _JAVA_OPTIONS system variable (and any related variables such as JAVA_TOOL_OPTIONS) and review the values for illegal flags or heap size settings larger than the machine's available RAM.
3Step 3: Set _JAVA_OPTIONS to a safe value such as '-Xms256m -Xmx8g' (or up to -Xmx16g if the machine has sufficient RAM); remove any unknown or application-specific flags that were not intentionally set for the gateway.
4Step 4: Save the changes and restart the on-premises data gateway service on every node in the cluster.
5Step 5: Rerun the pipeline and verify the copy activity completes; if the error persists, temporarily clear _JAVA_OPTIONS entirely to isolate whether the variable is the root cause.

Frequently asked questions

How do I know which environment variable is causing the invalid JVM argument?

Check _JAVA_OPTIONS, JAVA_TOOL_OPTIONS, and JDK_JAVA_OPTIONS in both user and system environment variables. Temporarily rename each one to isolate which contains the problematic flags, then correct or remove the offending entry.

Is there a safe default value I can set for _JAVA_OPTIONS on the gateway?

Yes. Microsoft's guidance recommends '-Xms256m -Xmx16g' for machines with sufficient RAM. For machines with 8 GB or less, use '-Xms256m -Xmx4g' to avoid over-allocation. Always restart the gateway service after changing this value.