App Hangs on Startup: How to Find the Blocking Connection

Why apps get stuck at startup

Many services check their dependencies before they accept traffic: a database, a cache, an internal API. That check is a network connection. If the address is wrong, one of two things happens:

• Connection refused - the host is reachable but nothing listens on that port. The connect fails at once.
• No answer - packets are dropped (wrong host, firewall). The connect waits. With no timeout, it waits forever, and the app looks "running" in ps but never serves a request.

Either way, the last line in the log is the clue.

Step 1: read the last lines of the log

curl -s http://localhost:8080/health      # no answer
tail -n 8 /var/log/app.log

Example output:

Connecting to upstream service at 127.0.0.1:9999...
ERROR: Cannot reach upstream service at 127.0.0.1:9999: [Errno 111] Connection refused
FATAL: upstream unavailable, exiting

The app tells you exactly which host and port it tried. Write them down.

Step 2: find where the dependency really listens

List listening TCP ports and the process behind each one:

ss -ltnp          # or: netstat -tlnp

LISTEN 0  128  0.0.0.0:5000  0.0.0.0:*  users:(("python3",pid=41,fd=3))

Confirm the dependency answers on that port:

curl -s http://localhost:5000/health

If it answers on 5000 but the app dials 9999, the config is wrong, not the dependency.

Step 3: correct the config

; config.ini
[upstream]
host = 127.0.0.1
port = 5000      ; was 9999 - nothing listens there

Restart the app (or let its supervisor restart it) and confirm:

tail -n 3 /var/log/app.log
curl -s http://localhost:8080/health

Change the config, not the dependency. Other services may already use the dependency on its current port.

When the process hangs with no log output

If the app prints nothing and never exits, find out what it is waiting on:

# Which connections does the process have open?
ss -tnp | grep <pid>

# Which system call is it blocked in?
strace -p <pid>

A connection in state SYN-SENT means the app is waiting for a host that does not answer. For Python apps, py-spy dump --pid <pid> (if installed) prints the current stack and shows the exact line that is blocked.

Prevent silent hangs: always set a timeout

The worst startup bug is one with no error and no progress. Always give a network call a timeout:

import socket

def check_upstream(host, port, timeout=5):
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError as e:
        print(f'ERROR: cannot reach {host}:{port}: {e}')
        return False

Most clients have a timeout option: requests.get(url, timeout=5), psycopg2.connect(..., connect_timeout=5), redis.Redis(socket_connect_timeout=5). Then decide what happens on failure: retry with backoff, exit with a clear error, or start in a degraded mode. Never wait forever.

Checklist

1. Read the last log line and note the host and port.
2. Run ss -ltnp to see the real listening ports.
3. curl the dependency directly.
4. Correct the host or port in the config.
5. Add a timeout so the next mistake fails fast.