Normally, the JVM can figure out how much RAM is available on the system and automatically set a sensible upper bound for heap memory usage. On certain shared hosting environments, however, this doesn’t always work perfectly. If Metabase fails to start with an error message like
java.lang.OutOfMemoryError: Java heap space
You’ll just need to set a JVM option to let it know explicitly how much memory it should use for the heap space:
java -Xmx2g -jar metabase.jar
Adjust this number as appropriate for your shared hosting instance. Make sure to set the number lower than the total amount of RAM available on your instance, because Metabase isn’t the only process that’ll be running. Generally, leaving 1-2 GB of RAM for these other processes should be enough; for example, you might set
1g for an instance with 2 GB of RAM,
2g for one with 4 GB of RAM,
6g for an instance with 8 GB of RAM, and so forth. You may need to experiment with these settings a bit to find the right number.
As above, you can use the environment variable
JAVA_OPTS to set JVM args instead of passing them directly to
java. This is useful when running the Docker image,
docker run -d -p 3000:3000 -e "JAVA_OPTS=-Xmx2g" metabase/metabase
If the Metabase instance starts and runs for a significant amount of time before running out of memory, there might be an event (i.e. a large query) triggering the
OutOfMemoryError. One way to help diagnose where the memory is being used is to enable heap dumps when an OutOfMemoryError is triggered. To enable this, you need to add two flags to the
java -Xmx2g -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/a/directory -jar metabase-jar
-XX:HeapDumpPath flag is optional, with the current directory being the default. When an
OutOfMemoryError occurs, it will dump an
hprof file to the directory specified. These can be large (i.e. the size of the
-Xmx argument) so ensure your disk has enough space. These
hprof files can be read with many different tools, such as
jhat included with the JDK or the Eclipse Memory Analyzer Tool.
If you find an error regarding file permissions, like Metabase being unable to read a SQLite database or a custom GeoJSON, check out the section “Metabase can’t read to/from a file or directory” in our Docker troubleshooting guide.