// troubleshooting guide · metabase

Metabase OutOfMemoryError: Java Heap Space

Status
Workaround available
platforms:
Self-hosted (JAR, Docker, Kubernetes)
updated:
November 16, 2026
reports:
3
Method
how we research
Share

RUNBOOK · metabase/out-of-memory4 FIXES

// quick answer

Metabase runs on the JVM and crashes with 'java.lang.OutOfMemoryError: Java heap space' when the heap is too small for syncs or heavy queries. Raise the heap with -Xmx (JAVA_OPTS in Docker) and capture a heap dump if it keeps happening.

Most likely fix: Give the JVM more heap

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Give the JVM more heap

    1. 01JAR: start with java -Xmx2g -jar metabase.jar (or more)
    2. 02Docker: set JAVA_OPTS=-Xmx2g
    3. 03Keep the heap below the container's memory limit
    Did this fix it?
  2. FIX 2Capture a heap dump

    1. 01Add -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/some/dir
    2. 02Open the dump in Eclipse Memory Analyzer or VisualVM to find the query or job using memory
    Did this fix it?
  3. FIX 3Run a supported Java version

    1. 01Check the Java version Metabase's docs require for your release
    2. 02Upgrade Java and restart
    Did this fix it?
  4. FIX 4Reduce memory pressure

    1. 01Limit row counts on exports and big questions
    2. 02Reduce sync and scan frequency for large databases
    Did this fix it?

SANDBOX · metabase RUNS IN YOUR BROWSER

Try it: browse a sample shop and watch visitors, funnels and live data arrive

A hands-on Metabase-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

Metabase becomes very slow, stops responding or restarts, and the logs show java.lang.OutOfMemoryError.

Why it happens

  • C-01Heap too small for the number of users and queries
  • C-02Large queries or exports loaded into memory
  • C-03Database syncs on large schemas
  • C-04Container memory limit lower than the JVM heap
  • C-05Unsupported Java version

// this guide also covers

  • metabase outofmemoryerror
  • metabase java heap space
  • metabase crashing
  • metabase memory requirements

Still not working?

If Metabase keeps failing, you're not alone. See every Metabase problem users report or the alternatives people switch to.

Done fighting Metabase? Our small team builds your own Metabase alternative, or any software you need: web, mobile, games, desktop. Price agreed together.

Talk to us

Watch Metabase Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other Metabase errors

All 14 Metabase errors and fixes →