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 126.96.36.199, user joeblow, database testdbThis 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_databaseThere'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.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.