java network_error ai_generated true

java.rmi.ConnectException: Connection refused to host

ID: java/rmi-connection-refused

Also available as: JSON · Markdown
80%Fix Rate
85%Confidence
40Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

The RMI client cannot connect to the RMI registry or remote object. Commonly caused by the RMI registry not running, firewall blocking the port, or java.rmi.server.hostname resolving to a non-routable address (like 127.0.0.1 in Docker).

generic

Workarounds

  1. 88% success Set java.rmi.server.hostname to the externally reachable IP/hostname of the server 
    1. Add -Djava.rmi.server.hostname=<external-ip> to the server JVM arguments. 2. In Docker, set this to the host machine's IP or the Docker service name. 3. Verify the client can resolve and connect to this hostname. 4. Check with 'netstat -tlnp | grep <rmi-port>' that the RMI registry is listening.
  2. 82% success Fix RMI port assignment to use fixed ports instead of dynamic ports for firewall compatibility 
    1. Set the registry port explicitly: LocateRegistry.createRegistry(1099). 2. For exported remote objects, use a fixed port: UnicastRemoteObject.exportObject(obj, 1100). 3. Open both ports in the firewall. 4. In newer architectures, consider replacing RMI with gRPC or REST, which are more container-friendly.

Dead Ends

Common approaches that don't work:

  1. Only checking if the RMI registry port is open without verifying hostname resolution 70% fail

    RMI uses a two-phase connection: first to the registry, then to the server object's advertised hostname. Even if the registry is reachable, the stub may contain a hostname (like the container ID in Docker) that the client cannot resolve.

  2. Disabling the firewall entirely instead of opening the specific RMI ports 65% fail

    RMI uses dynamic ports for remote objects in addition to the registry port. Disabling the entire firewall is a security risk. The correct approach is to fix the port assignment, not remove the firewall.

Error Chain

Leads to:
Preceded by:
Frequently confused with: