Important: This issue typically indicates that the application is consuming more memory than the current JVM (Java Virtual Machine) configuration allows, or that a specific process is causing a memory leak.
Before you begin
You will need:
Developer access to the ColdFusion or Lucee environment.
Access to the ColdFusion Administrator or the server's command line.
Ability to view and interpret application logs.
Identify the source of the memory exhaustion
To determine if the issue is a general system limitation or a specific application leak, check the following:
Review the Error Logs. Locate the ColdFusion or Lucee error logs. Look for specific "Out of Memory" (OOM) errors.
ColdFusion: Typically found in the
cfusion/logsorcfusion/logs/error_xxx.logdirectory.Lucee: Typically found in the
lucee/logsdirectory.
Check the Java Heap Status. Use the ColdFusion Administrator or a monitoring tool to view the current heap usage.
In the ColdFusion Administrator, navigate to Server Settings > Java.
Observe the "Heap Size" and the current usage percentage.
Analyze the frequency of the error.
Consistent Growth: If memory usage climbs steadily and never drops, a memory leak is likely present in the code or a specific component.
Spike on Specific Action: If the error only occurs during a specific task (e.g., generating a large PDF or processing a large CSV), the task requires a more efficient coding approach or a larger heap allocation.
Troubleshooting common causes
Memory leaks in code
If a specific page or function consistently causes the heap to spike, investigate the following:
Large Collections: Ensure you are not loading thousands of records into a
CollectionorArraysimultaneously. Use aQueryand process records in a loop instead.Unclosed Resources: Ensure that database connections, file handles, and network sockets are closed properly.
Static Variables: Avoid storing large amounts of data in
Applicationscope orSessionscope unless necessary, as these persist in memory.
Large data processing
If the error occurs during a specific, high-demand operation:
Chunking: Break large data exports or imports into smaller "chunks" to process sequentially rather than all at once.
Streaming: Use streaming methods for file uploads or downloads to avoid loading the entire file into the Java heap.
Adjusting the Heap Size
If the application requires more memory to function normally under expected loads, you may need to increase the maximum heap size.
Warning: Increasing the heap size may allow the application to run, but it will not fix a memory leak. If a leak exists, the application will eventually exhaust the new, larger limit.
Identify the configuration file.
ColdFusion: Typically
[cf_install_dir]/cfusion/VmOptionsLucee: Typically
[lucee_install_dir]/lucee/VmOptions
Locate the
-Xmxparameter.This parameter defines the maximum heap size.
Increase the value.
Change the value to a higher amount (e.g.,
-Xmx4gfor 4GB).
Restart the service.
Restart the ColdFusion or Lucee service for the changes to take effect.
Confirm the result
The application no longer throws "Out of Memory" errors during standard operation.
The error logs do not show recurring "Java Heap" or "OutOfMemoryError" entries.
Memory usage remains stable during high-traffic periods.
If the error persists after increasing the heap
If the application still crashes after a significant increase in the -Xmx value, a memory leak is likely present.
Generate a Heap Dump. Configure the JVM to generate a heap dump on error by adding
-XX:+HeapDumpOnOutOfMemoryErrorto theVmOptionsfile.Analyze the Dump. Use a tool like Eclipse Memory Analyzer (MAT) or VisualVM to inspect the heap dump and identify which objects are consuming the most memory.
Identify the offending code. Locate the specific class or method in your application responsible for the leak and refactor the code.
Limitations
This procedure does not address issues caused by insufficient physical RAM on the host server.
This procedure does not address issues caused by the operating system's "swap" space being exhausted.
Increasing the heap size beyond the physical memory available on the server will lead to system instability.
