Troubleshooting

Common issues and solutions.

Local Development

Daemon Won't Start

Symptom: postbase start fails or hangs

Solutions:

1. Check Docker is running:

   docker info

2. Check port availability:

   lsof -i :9432
   lsof -i :5432

3. Remove stale state:

   rm -f ~/.postbase/state.json
   postbase start

4. Check Docker logs:

   docker logs postbase-postgres

Port Already in Use

Symptom: Error: Port 5432 already in use

Solutions:

1. Find and stop the process:

   lsof -i :5432
   kill <PID>

2. Use a different port:

   postbase start --pg-port 5433

3. Stop existing PostgreSQL:

   # macOS with Homebrew
   brew services stop postgresql
    
   # Linux
   sudo systemctl stop postgresql

Cannot Connect to Database

Symptom: Connection refused or ECONNREFUSED

Solutions:

1. Check daemon is running:

   postbase status

2. Verify PostgreSQL container:

   docker ps | grep postbase

3. Test direct connection:

   psql "postgresql://postgres:postgres@localhost:5432/postgres"

4. Restart the daemon:

   postbase stop
   postbase start

Migration Checksum Mismatch

Symptom: Checksum mismatch for migration X

Cause: Migration file was modified after being applied.

Solutions:

1. If intentional, reset the checksum:

   UPDATE _postbase_migrations 
   SET checksum = '<new_checksum>' 
   WHERE name = 'migration_name';

2. If accidental, restore the original file from version control.

3. Create a new migration instead of modifying existing ones.

Cloud Platform

Authentication Failed

Symptom: 401 Unauthorized or Authentication required

Solutions:

1. Re-authenticate:

   postbase cloud logout
   postbase cloud login

2. Check credentials file:

   cat ~/.postbase/cloud.json

3. Verify token hasn't expired (tokens are long-lived but may be revoked).

Database Provisioning Stuck

Symptom: Database stuck in "provisioning" status

Solutions:

1. Check Railway status: https://status.railway.app

2. Wait a few minutes (provisioning can take 2-5 minutes)

3. Check detailed status:

   postbase cloud databases list -p <project> --json

4. Contact support if stuck for >10 minutes

Cannot Connect to Cloud Database

Symptom: Connection refused or SSL errors

Solutions:

1. Get correct connection string:

   postbase cloud url <database> -p <project>

2. Ensure SSL is disabled (Railway proxy doesn't require SSL):

   postgresql://...?sslmode=disable

3. Check network connectivity:

   telnet <host> <port>

Backup Failed

Symptom: Backup shows "failed" status

Solutions:

1. Check backup service health:

   curl https://postbase-backup-service.up.railway.app/health

2. Check database size (large databases may timeout)

3. Retry the backup:

   postbase cloud backups create -p <project> -d <database>

4. Check backup service logs (contact support)

PITR Issues

WAL Receiver Not Running

Symptom: pitr status shows "WAL Receiver: NOT RUNNING"

Solutions:

1. Check receiver status:

   postbase cloud pitr receiver -p <project> -d <database>

2. Restart the receiver:

   postbase cloud pitr restart-receiver -p <project> -d <database>

3. Verify database supports replication:

   • Must use ghcr.io/zeroexcore/postbase:postgres-15-pitr image

4. Check backup service health:

   postbase cloud pitr service-status -p <project> -d <database>

High WAL Lag

Symptom: WAL lag is >5 minutes

Causes:

• High write volume on database
• Network issues between Railway and backup service
• Backup service overloaded

Solutions:

1. Monitor lag:

   postbase cloud pitr receiver -p <project> -d <database>

2. Restart receiver:

   postbase cloud pitr restart-receiver -p <project> -d <database>

3. Contact support if lag persists

Cannot Restore to Target Time

Symptom: Target time outside recovery window

Solutions:

1. Check recovery window:

   postbase cloud pitr status -p <project> -d <database>

2. Choose a time within the window

3. The earliest time is the base backup time

4. The latest time is the most recent WAL segment

SDK Issues

Type Errors

Symptom: TypeScript errors when using SDK

Solutions:

1. Regenerate types:

   postbase types generate --database myapp --all --output ./src/db/types.ts

2. Ensure types match SDK version:

   npm update @postbase/sdk

3. Check import path:

   import type { Database } from './db/types'

Connection Pool Exhausted

Symptom: Connection pool exhausted or slow queries

Solutions:

1. Close unused connections:

   await db.close()

2. Increase pool size:

   const db = createClient({
     connectionString: '...',
     pool: { max: 20 }
   })

3. Use connection pooling (e.g., PgBouncer) for high-traffic apps

Realtime Not Receiving Events

Symptom: Subscriptions don't receive updates

Solutions:

1. Verify triggers exist:

   \d users  -- Check triggers section

2. Test NOTIFY manually:

   NOTIFY users, '{"test": true}';

3. Check channel name matches table:

   db.channel('users')  // Must match NOTIFY channel

4. Check for connection errors:

   channel.on('error', console.error)

Getting Help

Debug Information

Collect this info when reporting issues:

# CLI version
postbase --version
 
# System info
uname -a
node --version
docker --version
 
# Daemon status
postbase status --json
 
# Docker containers
docker ps
 
# Recent logs
docker logs postbase-postgres --tail 50

Support Channels

• GitHub Issues: https://github.com/zeroexcore/postbase/issues
• Discord: Coming soon
• Email: support@postbase.sh

Known Issues

Check the GitHub issues for known problems:

https://github.com/zeroexcore/postbase/issues?q=is%3Aopen+label%3Abug