diff --git a/doc/src/sgml/trouble.sgml b/doc/src/sgml/trouble.sgml index a1b100180bf..7ae6dbaa2dc 100644 --- a/doc/src/sgml/trouble.sgml +++ b/doc/src/sgml/trouble.sgml @@ -2,29 +2,137 @@ Troubleshooting - Client Connections - - If you get the following error message from a - Postgres - command (such as psql or - createdb): + Postmaster Startup Failures + + There are several common reasons for the postmaster to fail to start up. + Check the postmaster's log file, or start it by hand (without redirecting + standard output or standard error) to see what complaint messages appear. + Some of the possible error messages are reasonably self-explanatory, + but here are some that are not: + + + -connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? +FATAL: StreamServerPort: bind() failed: Address already in use + Is another postmaster already running on that port? - - it is usually because either the postmaster is not running, - or you are attempting to connect to the wrong server host. - If you get the following error message: - + This usually means just what it suggests: you accidentally started a + second postmaster on the same port where one is already running. + However, if the kernel error + message is not "Address already in use" or some variant of that wording, + there may be a different problem. For example, trying to start a + postmaster on a reserved port number may draw something like -FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) +$ postmaster -i -p 666 +FATAL: StreamServerPort: bind() failed: Permission denied + Is another postmaster already running on that port? + + + + +IpcMemoryCreate: shmget failed (Invalid argument) key=5440001, size=83918612, permission=600 +FATAL 1: ShmemCreate: cannot create region + + A message like this probably means that your kernel's limit on the size + of shared memory areas is smaller than the buffer area that Postgres + is trying to create. (Or it could mean that you don't have SysV-style + shared memory support configured into your kernel at all.) As a temporary + workaround, you can try starting the postmaster with a smaller-than-normal + number of buffers (-B switch). You will eventually want to reconfigure + your kernel to increase the allowed shared memory size, however. + You may see this message when trying to start multiple postmasters on + the same machine, if their total space requests exceed the kernel limit. + + + + +IpcSemaphoreCreate: semget failed (No space left on device) key=5440026, num=16, permission=600 + + A message like this does not mean that you've run out + of disk space; it means that your kernel's limit on the number of SysV + semaphores is smaller than the number Postgres wants to create. As above, + you may be able to work around the problem by starting the postmaster with + a reduced number of backend processes (-N switch), but you'll eventually + want to increase the kernel limit. + + + + + + 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. + - it means that the site administrator started the postmaster - as the wrong user. Tell him to restart it as - the Postgres superuser. -