When PostgreSQL will not start on Linux, do not begin by deleting files or changing permissions. First capture the earliest PostgreSQL error, identify the exact cluster and systemd unit involved, and then fix that specific failure. The useful evidence is usually in systemctl status, the systemd journal, PostgreSQL’s own log, or a controlled foreground start with pg_ctl.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
This workflow covers the common causes—port conflicts, permission errors, wrong data directories, stale postmaster.pid files, crash recovery, socket failures, shared-memory limits, and systemd timeouts—while keeping database files and recovery evidence intact.
As an Amazon Associate I earn from qualifying purchases.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Before changing anything, preserve the evidence
A failed start can leave the most useful clue in a log line that disappears after a restart or a configuration edit. Save the service output and note the time of the failed attempt before making changes.
- Do not run
initdbagainst an existing data directory. - Do not remove WAL files or disable
fsyncas a quick fix. - Do not recursively change ownership or permissions until you know which path is wrong.
- Do not delete
postmaster.piduntil you have checked the recorded process ID and confirmed that no PostgreSQL instance uses the directory.
Record the distribution, PostgreSQL major version, data-directory path, configured port, and the exact service unit. Package layouts differ, so a command that is correct on one Linux distribution can target the wrong cluster on another.
1. Identify the service unit and capture systemd output
Start with the unit that actually manages the cluster. A generic unit may be called postgresql.service; package-managed installations can use an instance unit such as [email protected] or postgresql-16.service.
systemctl list-units --type=service | grep -i postgresAfter you have the name, inspect its current state and the boot journal:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
sudo systemctl status postgresql.service
sudo journalctl -u postgresql.service -b --no-pagerReplace postgresql.service with the unit you found. If the service failed during an earlier boot, remove -b or select the relevant boot explicitly. Read the PostgreSQL message in the journal rather than relying on the final systemd summary such as an exit status of 1. Systemd reports that the wrapper failed; PostgreSQL usually explains why.
2. Read PostgreSQL’s own log and find the first concrete error
PostgreSQL’s official troubleshooting advice is to check the server log or start the server by hand without redirecting standard output or standard error. Locate the configured log_directory and log_filename in postgresql.conf, or inspect the unit file and journal for the path used by the package.
In the failed attempt, find the earliest FATAL, PANIC, or meaningful LOG line. Later messages often describe the consequence—such as systemd stopping a process—rather than the cause. Keep the surrounding lines, including timestamps, error numbers, paths, and hints.
A useful sequence is:
- Note the timestamp of the start attempt.
- Open the PostgreSQL log covering that timestamp.
- Read from the first startup line forward.
- Copy the first actionable error and the lines immediately before and after it.
If the service wrapper truncates the message, reproduce the start in the foreground.
3. Reproduce the start in the foreground
Run pg_ctl as the database service account and point it at the same cluster directory used by the unit. The directory below is only an example; use the path from the package or unit configuration.
sudo -u postgres pg_ctl -D /var/lib/postgresql/<major>/main start -wThe -D option selects the data directory and -w waits for startup, allowing errors to appear directly. The same directory can be supplied through the PGDATA environment variable, but do not guess it. A foreground start against the wrong directory can create a second, confusing failure.
If the command says the server is already running, stop and investigate rather than forcing another start. If it prints a concrete error, use that message to choose the branch below.
Match the exact message to the correct fix
Port conflict: “Address already in use”
This means another process already owns the configured TCP port. PostgreSQL commonly uses 5432, but the cluster may be configured differently.
ss -ltnp | grep ':5432'Check the port setting in the intended cluster’s configuration and compare it with the listener. The owner may be another PostgreSQL cluster, a manually started instance, or an unrelated service. Identify the process and its data directory before stopping anything.
- If a duplicate PostgreSQL cluster is running, stop only the instance you have confirmed is redundant.
- If an unrelated service owns the port, coordinate a stop or choose a different PostgreSQL port.
- If you change PostgreSQL’s port, update every client, connection pool, firewall rule, monitoring check, and application setting that should reach this cluster.
PostgreSQL’s own startup hint asks whether another postmaster is already running on port 5432. Treat that as a diagnostic prompt, not proof that the other process is safe to terminate.
Permission-denied errors on the socket or data directory
Permission failures can involve the data directory, a parent directory, a configuration file, a Unix-domain socket directory, or a restricted TCP port. Test access as the service account rather than as your administrative shell user.
sudo -u postgres test -r /var/lib/postgresql/<major>/main/postgresql.conf
sudo -u postgres test -x /var/lib/postgresql/<major>/main
sudo -u postgres test -r /var/lib/postgresql/<major>/main/pg_hba.confAlso check every parent directory in the path: the account needs execute (traverse) permission on each one. Confirm that the account named by the unit is really postgres; some packaged or containerized deployments use a different service identity.
Recommended Free Tools
Repair ownership and modes using the defaults documented for your distribution and package. Avoid broad recursive commands copied from an unrelated system: they can expose database files, alter special permissions, or make a later recovery harder. If the error names a socket directory, verify that directory exists, is writable by the service account, and is on a mounted filesystem with free space.
Wrong, missing, or mismatched data directory
A cluster is more than a path in a shell command. Compare the unit’s ExecStart, any -D option, the PGDATA environment, and any config_file option with the directory you intend to start.
A normal cluster directory contains markers such as:
PG_VERSIONbase/global/postgresql.conf
If those files are absent, you may be pointing at an empty mount, a backup copy, or the parent of the real cluster. Mount the expected filesystem before starting, and verify that the path is not a symlink to an unavailable location.
The server binary and cluster major version must also be compatible. A newer or older binary cannot be assumed to open an existing cluster directly. Use the package’s intended service unit and binaries; do not initialize a replacement cluster merely because the configured path looks empty.
Stale postmaster.pid
The PID file is state, not disposable debris. PostgreSQL checks it to determine whether the data directory is already in use and to record startup details.
Open the file and note the recorded PID, then check whether that process still exists and whether any listener belongs to it. Use the cluster directory in every check so that you do not confuse two installations.
sudo -u postgres pg_ctl -D /var/lib/postgresql/<major>/main status
ps -p <pid-from-file> -o pid,ppid,user,cmd
ss -ltnp | grep ':5432'If the PID is live and its command line identifies PostgreSQL using this directory, do not remove the file. If the PID belongs to an unrelated process, stop and investigate the collision before taking action.
When the host crashed and no PostgreSQL process remains, preserve a copy of postmaster.pid and follow the recovery procedure for your distribution. Only after those checks establish that the directory is unused should the stale file be removed. Deleting it prematurely can allow two processes to use one cluster or destroy evidence about an unclean shutdown.
Crash recovery, replay, or a systemd timeout
A server can be alive but not yet accepting connections while it replays WAL after a crash or abrupt termination. Logs may say that recovery is in progress, that replay is advancing, or that the server is waiting for a checkpoint. Storage speed, WAL volume, and the state of the filesystem affect how long this takes.
Watch the PostgreSQL log while the start is running. If recovery messages continue to advance and the process is not being killed, waiting is safer than repeated restarts. A systemd timeout can terminate a process that is still recovering, so compare the timeout message with the PostgreSQL log before changing the unit.
Extend the unit’s startup timeout only after confirming all of the following:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match- The process is genuinely performing recovery rather than looping on the same error.
- The storage device and filesystem are healthy and mounted.
- There is enough free space for normal recovery activity.
- The longer timeout matches the service’s operational requirements.
Make the timeout change through the distribution’s supported systemd override mechanism, document it, and reload systemd before retrying. Do not use a longer timeout to hide a permission, port, or disk failure.
Unix-socket, reserved-port, and shared-memory errors
Socket and shared-memory failures are operating-system problems whose fixes depend on the exact errno and path. Read the kernel and PostgreSQL messages together.
- A reserved-port permission error can indicate that the configured TCP port is below the operating system’s unprivileged threshold or that the service lacks the required capability. Choose an appropriate port or apply the platform’s documented permission model.
- An inability to create a Unix socket can result from a missing or unwritable socket directory, a read-only mount, a full filesystem, or a stale socket file.
- Shared-memory errors can indicate an operating-system limit rather than a PostgreSQL configuration typo. Record the requested and available values before changing kernel settings.
- A “no space left” message requires checking the filesystem that contains the data directory, WAL location, temporary directory, and socket directory—not just the root filesystem.
Keep the exact path, errno, mount state, and resource values in your incident notes. Changing several limits at once makes it difficult to tell which action solved the failure.
Check the cluster and service account before retrying
Before another start, verify that the intended directory is mounted and readable, the service account is correct, and no duplicate process is using the same files. Confirm the configured port and socket location from the cluster’s configuration, not from an assumption based on defaults.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsIf you edited a configuration file, validate that the syntax and setting names are correct. Keep a copy of the previous file so you can revert a change that introduces a second error.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Restart the intended cluster
Use the same data directory and options that you diagnosed. For a package-managed service, restart the exact unit you identified rather than a similarly named generic unit.
sudo systemctl restart postgresql.serviceFor a direct, service-account-controlled start, use:
sudo -u postgres pg_ctl -D /var/lib/postgresql/<major>/main start -wDo not run both methods at the same time. They can target different clusters, create competing PID files, or produce a misleading port conflict.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Verify that the right server is accepting connections
A green systemd status only proves that a unit reported success. Verify the PID, endpoint, and cluster from the client’s perspective.
sudo -u postgres pg_ctl -D /var/lib/postgresql/<major>/main status
pg_isready -h 127.0.0.1 -p 5432
psql -h 127.0.0.1 -p 5432 -d postgres -c 'select version();'The first command reports the PID and command line for the specified data directory. pg_isready checks whether the endpoint is accepting connections. The psql query confirms which PostgreSQL build answered and proves that authentication and the selected database work.
If the application still fails, compare its host, port, socket directory, TLS settings, and credentials with the endpoint you just tested. An application can be healthy while pointed at a different host or cluster.
Choosing between plausible fixes
When more than one action appears possible, rank it by safety rather than speed alone.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Option | Preserves data and evidence | Addresses the first logged cause | Downtime impact | Reversibility |
|---|---|---|---|---|
| Wait for confirmed crash recovery | Yes; avoids interrupting replay | Yes, when logs show advancing recovery | May extend downtime | High |
| Change the PostgreSQL port | Yes | Yes, for a confirmed port collision | Clients need coordinated changes | High |
| Repair a narrowly identified permission | Usually, if limited to the named path | Yes, for a verified access error | Usually short | Moderate; record the old mode and owner |
| Remove a verified stale PID file | Preserves the cluster only when no process uses it | Yes, for a confirmed stale state file | Short, but unsafe if misdiagnosed | Low after deletion; preserve a copy first |
| Increase the systemd timeout | Yes | Only when timeout interrupts healthy recovery | Longer startup window | High through a documented override |
Any action that does not explain the first PostgreSQL error is a poor candidate for a production fix. Preserve logs, make one controlled change, and repeat the same verification commands.
Common traps that make the outage worse
- Deleting
postmaster.pidimmediately: a live server may still own the directory. - Running
initdbin the existing path: initialization is for a new cluster and can overwrite or conflict with existing data. - Removing WAL files: replay may depend on them; deleting them can turn a recoverable shutdown into data loss.
- Disabling
fsync: this trades a startup symptom for a durability risk and is not a repair. - Using a recursive ownership command from a different distribution: it can alter files that should retain special ownership or modes.
- Starting a second cluster to test a theory: it can create a port collision and obscure which instance serves clients.
- Restarting repeatedly during recovery: each interruption can lengthen recovery and erase the timing pattern needed to diagnose it.
When to stop and escalate
Escalate to your distribution or database administrator when the logs show storage I/O errors, repeated PANIC messages, missing or corrupt control files, unexplained WAL failures, or a cluster whose version and binary no longer match. Provide the preserved service output, the earliest PostgreSQL error, the unit name, the data-directory path, filesystem and mount information, and the commands already run. Do not send secrets from configuration files.
The safest Linux recovery is evidence-first: identify the exact unit and cluster, expose the first PostgreSQL error, make the smallest change that explains it, and verify the same endpoint your applications use.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
