If you’ve ever dealt with Java applications in production, you know there are few things more alarming than an OutOfMemoryError (OOM). One moment everything seems fine, and the next minute, your application stalls or even crashes, leaving both users and developers scrambling for answers.

The good news? You don’t have to just sit back and hope it never happens. The JVM actually gives us a way to respond automatically when an OOM occurs. By using the -XX:OnOutOfMemoryError option, we can ask the JVM to trigger a script that not only captures valuable diagnostic data (like heap dumps) but can also restart the application right away. In this guide, we’ll walk through how to do that using the yc-360 wrapper script, so your system recovers gracefully and you don’t lose precious time troubleshooting in the dark.

Handle OutOfMemoryError in Java with OnOutOfMemoryError

You might be wondering, why not just drop the recovery commands straight into the OnOutOfMemoryError option and call it a day?

Well, that’s where using a wrapper script really shines. Instead of hardcoding commands into your JVM options, you point them to a script that handles everything for you. This simple shift gives you:

• Consistency: The same script can run across all environments, dev, test, or production, so you don’t need to reconfigure each one separately.
• Flexibility: Want to tweak the recovery logic? Just update the script. No need to restart your application with new JVM flags every time.
• Reliability: The wrapper script can do more than just restart services. It can integrate with monitoring tools, capture heap dumps, and plug into your alerting pipeline.

In other words, the yc-360 wrapper script isn’t just a convenience. It’s your safety net for keeping applications stable when things go wrong.

Step 1a: Create an OOM Handler Script (Local Capture Mode)

In this mode, the OOM handler captures the diagnostic bundle locally. The generated ZIP file can later be analyzed using tools such as Eclipse Memory Analyzer Tool (MAT), VisualVM, JDK Mission Control (JMC), YourKit, JProfiler, HeapHero, JConsole, or JHat.

Example handler script (oom-handler-yc-360.sh):

#!/bin/bash
set -xe

## Execute yc-360 wrapper script to capture diagnostics on OOM
curl -sSLf https://tier1app.com/scripts/run_yc_360.sh | bash -s -- \
    -j ${JAVA_HOME} \
    -onlyCapture \
    -hd \
    -a ${APP_NAME}

This script runs the yc-360 wrapper in onlyCapture mode, ensuring that heap dumps and other metrics are collected, compressed into a ZIP archive, and stored locally for later retrieval.

Step 1b: Create an OOM Handler Script (Direct Upload Mode with yCrash Server)

In this mode, the captured OOM diagnostics are automatically transmitted to your yCrash server, eliminating the need for manual retrieval.

Example handler script (oom-handler-yc-360.sh):

#!/bin/bash
set -xe

## Execute yc-360 wrapper script to capture diagnostics and send to yCrash server on OOM
curl -sSLf https://tier1app.com/scripts/run_yc_360.sh | bash -s -- \
    -j ${JAVA_HOME} \
    -s ${YC_SERVER_URL} \
    -k ${API_KEY} \
    -hd \
    -a ${APP_NAME}

This script executes the yc-360 wrapper in onDemand mode, collecting heap dumps and metrics, and directly uploading them to the configured yCrash server instance.

What These Scripts Do

• Invoke the hosted run_yc_360.sh wrapper with the appropriate parameters.
• Capture heap dumps and relevant diagnostic data on OOM.
• (Optional best practice) Restart the affected Java service (e.g., Tomcat, JBoss, WildFly, GlassFish, Jetty, WebLogic) after the dump is taken, ensuring minimal downtime and automatic recovery.

To enable automatic restart, add the following snippet inside your oom-handler-yc-360.sh:

## Restart Java service (example: Tomcat 9)
# sudo systemctl restart tomcat9.service

Step 2: Configure the JVM Option

Add the following JVM flag to your application startup command (Tomcat, Jetty, Spring Boot, etc.):

-XX:OnOutOfMemoryError="/usr/local/bin/oom-handler-yc-360.sh"

Example (Tomcat with G1GC):

JAVA_OPTS="-Xmx1024m -XX:+UseG1GC -XX:OnOutOfMemoryError=/usr/local/bin/oom-handler-yc-360.sh"

Benefits of Handling OutOfMemoryError with OnOutOfMemoryError and yc-360 Script

Setting up OnOutOfMemoryError with the yc-360 wrapper script isn’t just a nice-to-have. It can be a game changer for production environments. Here’s why:

• Automated Heap Dump Capture: No need to log in at 2 AM when something breaks. The script automatically captures a heap dump the moment an OutOfMemoryError occurs, giving you the data you need for root cause analysis.
• Seamless Integration with yc-360-script: The wrapper script connects directly with yc-360-script, ensuring consistent analysis across all your environments without extra manual steps.
• Self-Healing Recovery: After collecting the diagnostic data, the script can restart your application service automatically. This means minimal downtime and a smoother experience for your end-users.
• Customizable for Your Needs: Want to add email alerts, Slack notifications, or log collection? The script is flexible and you can extend it to match your operational workflows.

In short, this setup transforms OOM errors from sudden, disruptive crashes into actionable events. You get insights, faster recovery, and peace of mind.

Conclusion

An OutOfMemoryError doesn’t have to mean panic, late-night firefighting, or guesswork. By combining the JVM’s -XX:OnOutOfMemoryError option with the yc-360 wrapper script, you can turn a potential disaster into a controlled, recoverable event.

Instead of blind crashes, your application will:

• Capture heap dumps automatically for diagnosis
• Restart itself to minimize downtime
• Optionally trigger alerts so your team stays informed

This approach works across any Java-based server or standalone application, making it a must-have for teams that value uptime, resilience, and faster root cause analysis.

If keeping your systems stable (and your weekends peaceful) matters to you, then setting up this recovery flow should be at the top of your checklist.