Client Connection Problems

Once you have a running postmaster, trying to connect to it with client applications can fail for a variety of reasons. The sample error messages shown here are for clients based on recent versions of libpq --- clients based on other interface libraries may produce other messages with more or less information.

connectDB() -- connect() failed: Connection refused
Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'?
    
This is the generic "I couldn't find a postmaster to talk to" failure. It looks like the above when TCP/IP communication is attempted, or like this when attempting Unix-socket communication to a local postmaster:
connectDB() -- connect() failed: No such file or directory
Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'?
    
The last line is useful in verifying that the client is trying to connect where it is supposed to. If there is in fact no postmaster running there, the kernel error message will typically be either "Connection refused" or "No such file or directory", as illustrated. (It is particularly important to realize that "Connection refused" in this context does not mean that the postmaster got your connection request and rejected it --- that case will produce a different message, as shown below.) Other error messages such as "Connection timed out" may indicate more fundamental problems, like lack of network connectivity.

No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
    
This is what you are most likely to get if you succeed in contacting a postmaster, but it doesn't want to talk to you. As the message suggests, the postmaster refused the connection request because it found no authorizing entry in its pg_hba.conf configuration file.

Password authentication failed for user 'joeblow'
    
Messages like this indicate that you contacted the postmaster, and it's willing to talk to you, but not until you pass the authorization method specified in the pg_hba.conf file. Check the password you're providing, or check your Kerberos or IDENT software if the complaint mentions one of those authentication types.

FATAL 1:  SetUserId: user 'joeblow' is not in 'pg_shadow'
    
This is another variant of authentication failure: no Postgres create_user command has been executed for the given username.

FATAL 1:  Database testdb does not exist in pg_database
    
There's no database by that name under the control of this postmaster. Note that if you don't specify a database name, it defaults to your Postgres username, which may or may not be the right thing.

NOTICE:  Unrecognized variable client_encoding
    
This isn't an error; in fact, it's quite harmless. You'll see this message at startup if you use a client compiled with MULTIBYTE support to connect to a server compiled without it. (The client is trying to tell the server what character set encoding it wants, but the server has no idea what it's talking about.) If the message bothers you, use a client compiled with the same options as the server.