Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pgAdmin 4 never finishes loading after you open it

ErrorpgAdmin 4 shows the loading spinner forever

Short answer

The desktop app starts a Python server and waits for it to answer. If that takes too long or the port is taken, the window just keeps loading. Open the log from File, View logs to see the real error, then raise the connection timeout or set a fixed port in the runtime settings.

  • Applies to pgAdmin 4 9.x, Windows 11, macOS, Linux desktop
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the log. It is the only place that says why the Python server did not come up.

    # Linux / macOS
    tail -n 50 ~/.pgadmin/pgadmin4.log
    # Windows (Command Prompt)
    type %APPDATA%\pgAdmin\pgadmin4.log
  2. 2Match what you see, then jump to its fix

    1. 1The log shows no error, and the problem is worse on a slow or busy machineThe server needs longer to start than the runtime waitsFix
    2. 2Another program on the machine already uses the port that the log shows, or the problem comes and goes between startsThe random port clashes with another applicationFix

What does the error look like?

  • pgAdmin 4 shows the loading spinner forever
  • pgAdmin won't start (eternal loading)

Cause 1 of 2

The server needs longer to start than the runtime waits

1Check

The runtime waits for the server only as long as its ConnectionTimeout setting. A slow machine can exceed it. Open File, Configure runtime to see the value.

# macOS: ~/Library/Preferences/pgadmin ; Linux: ~/.local/share/pgadmin/ ; Windows: %APPDATA%/pgadmin (runtime_config.json)

2Fix

In Configure runtime, raise ConnectionTimeout (seconds to wait for server startup), save, and restart pgAdmin.

# File > Configure runtime... > ConnectionTimeout

3Verify

pgAdmin opens its browser tree after restart.

# Check the last lines of pgadmin4.log show the server started

Confirmed by pgadmin.org

Did this fix it?

Cause 2 of 2

The random port clashes with another application

1Check

By default the runtime picks a random port, which can collide with another program. A fixed port avoids the clash.

# Windows: netstat -ano | findstr :5050   |   Linux/macOS: lsof -i :5050

2Fix

In Configure runtime, switch on FixedPort and set PortNumber to a free port, save, and restart.

# File > Configure runtime... > FixedPort = on, PortNumber = 5055

3Verify

pgAdmin starts, and the log shows the server on that port.

# Linux/macOS: lsof -i :5055

Confirmed by pgadmin.org

Did this fix it?

How do I stop it coming back?

  • Look at pgadmin4.log first whenever pgAdmin hangs; guessing wastes time.
  • Set a fixed port if you run many local tools.
  • Keep pgAdmin updated, as startup fixes ship in its release notes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.