Troubleshooting Confluence Configuration: Fixing "Connection Refused" and Timeout Errors

Understanding the Error

When maintaining Atlassian Confluence in a large enterprise setting, administrators frequently face a cascade of interlinked issues ranging from confluence connection refused to generic end-user reports of confluence not working. Because Confluence relies heavily on a complex Java technology stack (Apache Tomcat, Hibernate, Lucene) integrated with an external database and often a reverse proxy (Nginx, Apache, HAProxy), identifying the precise bottleneck is crucial for effective confluence troubleshooting.

The most severe symptom is a complete outage. End-users will see browser-level errors like ERR_CONNECTION_REFUSED or a reverse proxy error like 502 Bad Gateway. Looking in the logs, you might see exact Java exceptions such as: java.net.ConnectException: Connection refused org.apache.catalina.connector.ClientAbortException: java.io.IOException: Broken pipe java.lang.OutOfMemoryError: Java heap space

These errors indicate that the underlying Confluence JVM has either failed to bind to its configured port (typically 8090), has locked up due to Garbage Collection (GC) pauses causing a confluence timeout, or is unable to retrieve data from the backend database fast enough.

Step 1: Diagnose the Bottleneck

Before modifying your confluence configuration, you must systematically diagnose which layer of the stack is failing.

1. Check Service Status and Port Bindings If you are seeing a connection refused error, the first step is verifying if the Java process is actually running and listening. Use ps aux | grep confluence to check the process. Then, run netstat -tulpn | grep 8090 to verify Tomcat has successfully bound to the port. If the port is not listed, Tomcat either failed during startup or is bound to a different interface (e.g., 127.0.0.1 instead of 0.0.0.0).

2. Analyze the Application Logs Navigate to <CONFLUENCE_HOME>/logs/ and inspect atlassian-confluence.log. Tail the end of the file during a crash or slow period. If you see repeated GC warnings or OutOfMemoryError, your JVM is starving. If you see SQL exceptions or Timeout waiting for idle object, your database connection pool is exhausted.

3. Inspect Proxy and Load Balancer Logs A common cause of a confluence timeout, particularly during a confluence data migration (XML backups/restores), is the reverse proxy closing the connection prematurely. Check your Nginx error.log for upstream timeouts.

Step 2: Implement Configuration Fixes

Once the root cause is identified, proceed with the following configuration changes.

Fix 1: Resolving Connection Refused and Port Conflicts

If Confluence is not starting, verify the <CONFLUENCE_INSTALL>/conf/server.xml file. Ensure that the <Connector> element is correctly configured. A common misconfiguration is setting the address attribute to a local loopback when external access is required.

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
           maxThreads="200" minSpareThreads="10"
           enableLookups="false" acceptCount="10"
           debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"/>

Make sure no other service (like Jira or Bitbucket) is trying to claim port 8090 or the Tomcat shutdown port (usually 8000).

Fix 2: Tuning JVM Heap for Slow Performance

If your users are complaining about confluence slow performance, the most impactful fix is tuning the JVM. Open <CONFLUENCE_INSTALL>/bin/setenv.sh (or setenv.bat on Windows). Locate the CATALINA_OPTS variable.

For a medium-sized enterprise instance (e.g., 500-1000 users), you need at least 4GB to 8GB of heap. Ensure your minimum (-Xms) and maximum (-Xmx) heap sizes are identical to prevent overhead from dynamically resizing the heap.

CATALINA_OPTS="-Xms8192m -Xmx8192m -XX:+UseG1GC ${CATALINA_OPTS}"

Using the G1 Garbage Collector (-XX:+UseG1GC) is highly recommended by Atlassian for large heaps as it reduces long pause times that lead to timeouts.

Fix 3: Mitigating Timeouts during Data Migration

Confluence data migration (especially XML site imports) can take hours. Standard web servers will cut the connection after 60 seconds. If you are using Nginx, you must update your nginx.conf or site-specific configuration to allow for massive timeouts on the migration endpoints.

location / {
    proxy_pass http://confluence;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_connect_timeout 60s;
}

Additionally, ensure your database (e.g., PostgreSQL postgresql.conf) has max_connections set to a value significantly higher than the Confluence pool size (typically 100+ max connections).

Step 3: Verifying the Fix

After altering the confluence configuration, always perform a clean restart: stop the service, optionally clear the Tomcat work/ and temp/ directories, and start the service again. Monitor catalina.out during the boot process to ensure it reports Server startup in [X] milliseconds. Test high-stress actions like PDF exports or complex macros to verify that the slow performance and timeouts have been resolved.