Halo Error

Halo is an open-source blogging platform built with Java and Spring Boot. It is popular among individual publishers and

Halo is an open-source blogging platform built with Java and Spring Boot. It is popular among individual publishers and small teams because it can be deployed either as a standalone JAR or through Docker. However, a successful installation does not always guarantee a healthy production environment. Incorrect Java versions, unavailable databases, port conflicts, resource limits, and proxy misconfiguration can all interrupt normal operation.

This guide explains the most common Halo errors and how to diagnose them safely.

Port 8090 Is Already in Use

Halo listens on port 8090 by default. If another process occupies that port, startup may end with an error similar to:

Web server failed to start. Port 8090 was already in use.

Identify the process using the port before taking action:

lsof -i:8090

If the process is obsolete, stop it gracefully when possible. Use a forced termination only as a last resort:

kill <PID>

Alternatively, assign Halo a different port at startup:

java -jar halo.jar --server.port=9500

When Halo runs behind a reverse proxy, remember to update the proxy configuration as well. Changing only the application port can leave the domain returning a gateway error.

The Java Version Is Too Old

Halo 2.x requires Java 17 or a newer supported release. An older runtime usually produces an UnsupportedClassVersionError, often mentioning a class file version that the installed JVM cannot recognize.

Check the active runtime:

java -version

Install a compatible JDK if necessary, then verify that JAVA_HOME and the system PATH point to the intended version. Restart Halo after changing the runtime environment; updating an installation alone does not replace the JVM used by an already running service.

The Database Cannot Be Reached

Halo 2.x commonly uses PostgreSQL or MySQL as its external database. Typical connection errors include:

Connection refused
Access denied for user

These messages may indicate that the database service is stopped, the host or port is incorrect, or the supplied credentials are invalid. They can also occur when Halo and the database are running in separate Docker networks.

Test the connection with the database client before changing Halo settings. If both services run in containers, confirm that they share a network and that the database hostname resolves from Halo’s container:

docker network ls
docker network inspect <network-name>

The database should listen on an address reachable from the Halo container. Binding it only to 127.0.0.1 inside its own container can make it inaccessible to other services.

Runtime Failures

OutOfMemoryError

On a server with limited memory, Halo may terminate with:

java.lang.OutOfMemoryError: Java heap space

The JVM heap must fit within the memory available to the container or service. For a small installation, explicit limits can prevent the process from consuming the entire host:

java -Xms512m -Xmx768m -jar halo.jar

Leave enough memory for the operating system, database, reverse proxy, and file cache. Upgrading a very small server and reducing the number of active plugins can also lower memory pressure. For Docker deployments, inspect both the container limit and the host’s available memory rather than relying on the JVM settings alone.

File Permission Denied

Halo stores its working data under ~/.halo2 by default. If the application is started by a different user than the one that owns those files, startup may fail with Permission denied.

Identify the account running Halo and align ownership accordingly:

chown -R <halo-user>:<halo-user> ~/.halo2

Apply the same principle to mounted Docker volumes. A consistent, dedicated runtime account is usually safer than repeatedly changing permissions on every deployment.

Reverse Proxy and Access Problems

A domain that returns 502 Bad Gateway usually means Nginx or another proxy cannot obtain a valid response from Halo. Check the application first:

docker ps

For a JAR deployment, inspect the Java process and test Halo directly:

ps -ef | grep '[h]alo'
curl -I http://127.0.0.1:8090

If the local request succeeds, the issue is likely in the proxy. A typical Nginx configuration looks like this:

location / {
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

The proxy_pass port must match Halo’s actual port. Missing Host and forwarding headers may also affect redirects, generated URLs, and application security decisions.

After changing the configuration, validate it before reloading:

nginx -t
nginx -s reload

If direct access works but the domain does not, also verify DNS, firewall rules, and whether the proxy is using HTTPS correctly.

Theme and Plugin Failures

Theme Rendering Errors

A page may return an HTTP 500 error immediately after a theme is installed or activated. Common causes include incompatibility with the current Halo version, missing template files, or an invalid theme configuration.

Start by switching back to the default theme. If the site recovers, review the application log for TemplateException, missing template, or rendering-related messages. Compare the theme’s supported Halo versions with the installed release before updating either component.

Plugin Conflicts

If the administrator console becomes unstable after enabling a plugin, disable the plugin first. If that is impossible, stop Halo, back up the plugin directory, and remove or quarantine the conflicting plugin:

cp -r ~/.halo2/plugins ~/.halo2/plugins.backup

Then restart the application and inspect the logs. Avoid deleting plugin files while Halo is running, because the process may still hold references to loaded classes and resources.

A Reliable Troubleshooting Routine

For most Halo incidents, a short systematic check is more effective than making several configuration changes at once:

  1. Read the first relevant exception in the application log.
  2. Verify the Java version, listening port, and runtime user.
  3. Test the database from the same environment in which Halo runs.
  4. Confirm local HTTP access before investigating the reverse proxy.
  5. Review recent theme, plugin, and configuration changes.
  6. Back up data before replacing files or rolling back versions.

Most Halo errors are not mysterious failures; they are usually caused by a mismatch between the application, its runtime, and the surrounding infrastructure. Checking each layer in order—Java, database, storage, network, and proxy—can quickly narrow down the source and prevent unnecessary changes.