Startup Troubleshooting

PostgreSQL output distinguishes spawn, early-exit, and readiness failures; capture it first, then adjust the failing startup boundary.

Capture Failure Diagnostics

Use on-error before reproducing a startup problem:

import { LocalPostgresError, startPostgres } from 'local-postgres'

try {
  await startPostgres({
    dataDir: '.postgres',
    postgresOutput: 'on-error',
  })
} catch (error) {
  if (error instanceof LocalPostgresError) {
    console.error(error.diagnostics)
  }
  throw error
}

The error message also includes the captured output under Postgres diagnostics:. Use a log file when output must continue after readiness.

Failed to start the "postgres" process

The executable could not be spawned. Verify that the selected binary exists and is executable:

postgres --version

If the command is missing, continue with Binary Troubleshooting. If a configured managed cache is involved, verify that the cache directory and its extracted binaries are readable and executable by the current user.

Postgres exited before becoming ready

PostgreSQL started but exited before accepting connections. Read the attached diagnostics for the concrete FATAL or configuration message.

Common causes include:

• another server won a postmaster.pid race after the preflight check
• PostgreSQL could not bind the selected host, port, or socket
• a configuration value appended during initialization is invalid
• the data directory or socket directory is not writable

Fix the reported local fact. Do not remove postmaster.pid until Data Directory Troubleshooting confirms it is stale.

No space left on device

This message does not necessarily refer to disk storage. A DETAIL containing shmget(...) reports System V shared-memory capacity, while could not resize shared memory segment reports a different dynamic shared-memory path. Continue with Shared Memory Troubleshooting before changing PostgreSQL memory settings.

Timed out ... waiting for Postgres to become ready

PostgreSQL remained alive, but the readiness connection did not succeed before readinessTimeoutMs:

await startPostgres({
  dataDir: '.postgres',
  postgresOutput: 'on-error',
  readinessTimeoutMs: 10_000,
})

Increase the timeout only when diagnostics show a valid but slow startup. Bind errors, invalid configuration, filesystem permissions, and mismatched client addresses require fixing the underlying condition instead.