WildFly Fails to Start: Causes, Log Errors & Solutions

Hitting a boot failure when launching **WildFly** can bring your development or production environment to a halt. Fortunately, WildFly provides clear error codes in standalone/log/server.log to help identify the root cause.

1. Port Already in Use (java.net.BindException)

This is the single most common reason why WildFly fails to start. If another process (like Tomcat, Docker, or a previous unclosed WildFly instance) is using port 8080 (HTTP) or 9990 (Admin Console), WildFly aborts startup:

ERROR [org.jboss.msc.service.fail] (MSC service thread 1-1) MSC000001: Failed to start service jboss.http-listener:
    org.jboss.msc.service.StartException in service jboss.http-listener: WFLYUT0082: Could not start http listener
    Caused by: java.net.BindException: Address already in use: bind

How to Fix:

Option A: Override ports at startup (Recommended for quick testing)
You can pass system properties to change the HTTP or Management port on the fly without modifying XML files:

# Change HTTP port to 8081
$ ./standalone.sh -Djboss.http.port=8081

# Or apply a port offset (moves 8080 -> 8180 and 9990 -> 10090)
$ ./standalone.sh -Djboss.socket.binding.port-offset=100

Option B: Find and kill the process holding port 8080

# On Linux / macOS:
$ sudo lsof -i :8080
$ kill -9 <PID>

# On Windows (Command Prompt):
C:\> netstat -ano | findstr 8080
C:\> taskkill /F /PID <PID>

2. Unsupported Java / JDK Version Mismatch

Modern WildFly releases (WildFly 27 through WildFly 35+) require Java 17 LTS or Java 21 LTS. Running modern WildFly on Java 8 or Java 11 will result in an UnsupportedClassVersionError or cause the bootstrap server thread to crash immediately.

Conversely, running legacy versions of WildFly/JBoss on brand-new Java releases can cause boot freezes.

How to Fix:

Check your active Java runtime version using the command line:

$ java -version

Ensure that your JAVA_HOME environment variable points to a valid Java 17 or Java 21 JDK installation:

# On Linux / Ubuntu:
$ export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
$ sudo update-alternatives --config java

# On Windows:
C:\> set JAVA_HOME=C:\Program Files\Java\jdk-21

3. Unresolvable Network Interface or IP Address (WFLYSRV0082)

If you specify an IP address or hostname in standalone.xml that does not exist on your machine's physical or virtual network interfaces, WildFly throws a network resolution exception:

10:23:49,063 ERROR [org.jboss.as.controller.management-operation] (Controller Boot Thread) WFLYCTL0013: Operation ("add") failed - address: ([("interface" => "public")]) 
- failure description: {"WFLYCTL0080: Failed services" => {"org.wildfly.network.interface.public" => "WFLYSRV0082: failed to resolve interface public"}}

How to Fix:

To bind WildFly to all available network interfaces so it can accept external traffic, pass the -b flag at launch:

# Bind public endpoints to all network interfaces
$ ./standalone.sh -b 0.0.0.0

# Bind management console to all network interfaces as well
$ ./standalone.sh -b 0.0.0.0 -bmanagement 0.0.0.0

If you need to bind to a specific hostname, ensure it is properly mapped inside your /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows) file.

4. Corrupted standalone.xml Configuration File

Accidentally introducing invalid XML syntax, missing closing tags, or incompatible subsystem elements into standalone.xml triggers parsing errors during boot:

ERROR [org.jboss.as.server] WFLYSRV0058: Server boot has failed
Caused by: WFLYCTL0085: Failed to parse configuration: Unexpected element '{urn:jboss:domain:19.0}subsystem'

How to Fix: Restore Built-in Configuration Backups

WildFly automatically maintains an automated history of working configuration files every time the server boots successfully. You can easily roll back to a known working state without reinstalling the server:

1. Navigate to $WILDFLY_HOME/standalone/configuration/standalone_xml_history/current/.
2. Locate the latest working XML file (e.g., standalone.boot.xml or standalone.last.xml).
3. Copy it over your broken configuration file:

   $ cp standalone/configuration/standalone_xml_history/current/standalone.last.xml standalone/configuration/standalone.xml

5. Out of Memory (OOM) or Metaspace Crashes on Boot

When deploying heavy enterprise EAR archives or multiple microservices at startup, WildFly may crash before finishing the boot sequence due to insufficient JVM memory allocations.

java.lang.OutOfMemoryError: Java heap space
  or
java.lang.OutOfMemoryError: Metaspace

How to Fix:

Edit the memory parameters in your server launch configuration file:

• Linux/macOS: Edit $WILDFLY_HOME/bin/standalone.conf
• Windows: Edit $WILDFLY_HOME/bin/standalone.conf.bat

Increase the maximum heap size (-Xmx) and Metaspace settings:

# Example standalone.conf modification:
JAVA_OPTS="-Xms1024m -Xmx4096m -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=1024m"

6. Thread Deadlocks & Hanging Startup Diagnostics

If WildFly gets stuck halfway through booting without exiting or outputting errors, a deployed service or outbound resource adapter (such as a database connection pool or JMS broker lookup) is likely blocking the main controller thread.

How to Diagnose:

Generate a thread dump of the running WildFly Java process using jcmd:

# 1. Find the Process ID (PID) of WildFly
$ jps -l
14205 org.jboss.as.standalone

# 2. Trigger a Thread Dump
$ jcmd 14205 Thread.print > thread_dump.txt

Inspect thread_dump.txt for threads in the BLOCKED or TIMED_WAITING state to identify which resource or database driver is stalling startup.

Frequently Asked Questions (FAQs)

Q1: Where are the main WildFly boot logs located?

All boot log outputs are stored in $WILDFLY_HOME/standalone/log/server.log. If launching in domain mode, check $WILDFLY_HOME/domain/log/host-controller.log.

Q2: Why does WildFly fail to start when running inside a Docker container?

By default, WildFly binds to 127.0.0.1 (localhost), which is isolated inside the container. You must start WildFly with -b 0.0.0.0 in your Dockerfile or docker run command to expose ports to the host machine.

Q3: How do I start WildFly in debug mode to trace startup crashes?

Run the standalone script with the --debug flag: ./standalone.sh --debug. This opens port 8787 for remote JPDA debugging in your IDE.

Conclusion

Most WildFly boot failures stem from port collisions, incompatible Java versions, or unresolvable network interfaces. By analyzing standalone/log/server.log and applying the troubleshooting strategies in this guide, you can quickly resolve startup issues and get your application server back online.