Java Deployment Clinic: Start From the Symptom, Not the Stack Trace

A Java app that runs on your laptop and fails on a host is almost never a mystery. The JAR is the same file. What changes is the world around it: the port the platform listens on, the memory the container is allowed, the database it has to reach, the time it gets to start, and the disk it writes to. This clinic is organised by what you see, so you can start from the symptom and skip the guesswork.

Figures and platform behaviour checked in November 2026 against each provider's documentation.

Pick your symptom

If two symptoms appear together, start with memory. An app that is killed for using too much memory also looks slow, restarts, and loses whatever it kept in local files.

Read the right log first

Every platform keeps two logs that matter here: the build or deploy log, which shows how the image or JAR was made, and the runtime log, which shows what the app printed after it started. Read the runtime log from the top of the last start. The first exception is the cause; everything after it is usually a consequence.

Three lines are worth searching for straight away:

• UnsupportedClassVersionError means the JAR was compiled for a newer Java than the runtime on the host.
• Address already in use or no line at all about the web server starting means the port is wrong.
• A log that stops in the middle of normal output, followed by a restart, points to the process being killed from outside.

Check the environment, not the code

Most of the differences between your machine and the host are configuration. Compare four things before you change a line of code: the Java version (java -version locally, the base image or runtime setting on the host), the environment variables the app reads, the memory limit of the plan, and the port. If those match, the remaining causes are network rules and file storage, which have their own pages above.

The deployment guide shows a working setup step by step, and the Java Launchpad helps pick a plan that fits the app before you deploy it again.

A five-minute check before every deploy

Most of the problems in this clinic can be caught before the first deploy. Run through this list once per app and again whenever the plan or the platform changes:

1. Port: the app reads the platform's port, for example server.port=${PORT:8080}, and listens on all addresses, not only localhost.
2. Java version: the build target, the base image and the platform runtime use the same major version.
3. Variables: every value the app reads at startup is set on the host, and the app fails with a clear message when one is missing.
4. Memory: the heap is sized as a share of the container with -XX:MaxRAMPercentage, not with a fixed -Xmx copied from a laptop.
5. Database: the URL is in JDBC format, includes sslmode=require where the provider requires SSL, and the pool fits the plan's connection limit.
6. Files: nothing the app needs to keep is written to the local disk.
7. Health check: it points at a light endpoint and allows for the startup time you measured on the host.

Each point links to a symptom page above if it fails. Working through the list takes a few minutes; a failed deploy on a free tier can cost an evening.

When it is the plan, not the app

Some failures are limits of the plan you chose. A free tier that sleeps will always have a slow first request, and a 512 MB instance cannot hold a heap meant for 2 GB. The hosting comparison lists memory, sleep rules and price for each plan, so you can see whether a fix is a setting or an upgrade.

Sources

1. render.com/docs/web-services
2. render.com/docs/disks
3. devcenter.heroku.com/articles/dynos
4. devcenter.heroku.com/articles/connecting-heroku-postgres
5. docs.docker.com/engine/containers/resource_constraints