Skip to main content

Troubleshooting

Check Service Status​

curl -u admin:password https://api.foundrydb.com/managed-services/{id} \
  | jq '{status, created_at}'

Common statuses and what they mean:

StatusMeaning
PendingService creation queued
ProvisioningVM being set up
RunningHealthy and accepting connections
StoppedShut down by user request
ErrorProvisioning or health check failed
UpgradingVersion upgrade in progress

Connection Refused​

Symptom: Client cannot connect; connection refused or timed out.

Checklist:

  1. Your IP is in allowed_cidrs: 
    curl -u admin:password https://api.foundrydb.com/managed-services/{id} | jq '.allowed_cidrs'
  2. The service status is Running (not Stopped or Error)
  3. You are connecting to the correct port for the engine (see Network Security)
  4. DNS resolves correctly: 
    dig +short yourdb.foundrydb.com

Authentication Failed​

Symptom: FATAL: password authentication failed or similar.

  1. Reveal the current password: 
    curl -u admin:password -X POST \
      https://api.foundrydb.com/managed-services/{id}/database-users/{username}/reveal-password
  2. Confirm you are using the correct username — default is app_user (varies by engine)
  3. Check for special characters in the password that need URL-encoding in connection strings

TLS / Certificate Errors​

Symptom: SSL SYSCALL error or certificate verify failed.

  • The certificate is issued for the service's DNS hostname. Always connect via hostname, not IP address.
  • If you see certificate has expired, contact support — automatic renewal may have been disrupted.
  • For clients that cannot use the system CA bundle, download the certificate: 
    echo | openssl s_client -connect yourdb.foundrydb.com:5432 -starttls postgres 2>/dev/null \
      | openssl x509 > server.crt

Replication Lag​

Symptom: Replica reads are stale; replication_lag_seconds metric is elevated.

  1. Check current lag: 
    curl -u admin:password \
      "https://api.foundrydb.com/managed-services/{id}/metrics?metric=replication_lag_seconds&period=1h"
  2. Lag spikes during bulk writes are normal and should recover within seconds
  3. Persistent lag (>60 seconds) may indicate replica node resource exhaustion — check cpu and disk_iops metrics
  4. If the replica is marked disconnected, add a new replica and remove the lagging one

Disk Full​

Symptom: Writes fail; error message mentions no space left on device.

  1. Check disk usage: 
    curl -u admin:password \
      "https://api.foundrydb.com/managed-services/{id}/metrics?metric=disk&period=1h"
  2. Expand storage — takes effect without downtime: 
    curl -u admin:password -X POST \
      https://api.foundrydb.com/managed-services/{id}/storage/expand \
      -H "Content-Type: application/json" \
      -d '{"storage_size_gb": 200}'
  3. If disk is at 100% and writes are blocked, stop the service, expand, then restart

Backup Failures​

Symptom: Backup status is failed; scheduled backups not completing.

  1. List recent backups and check error messages: 
    curl -u admin:password \
      "https://api.foundrydb.com/managed-services/{id}/backups?limit=5" \
      | jq '.backups[] | {id, status, error_message, created_at}'
  2. Common causes:
    • Disk space too low on the backup volume (expand storage)
    • Backup exceeded the 30-minute timeout (usually caused by very large databases — contact support)

High CPU / Memory​

Symptom: Slow queries; cpu or memory metric is consistently above 80%.

  1. Review query statistics (PostgreSQL): 
    curl -u admin:password \
      "https://api.foundrydb.com/managed-services/{id}/metrics/query-stats?limit=10&order=total_time"
  2. Scale up to a larger compute plan: 
    curl -u admin:password -X POST \
      https://api.foundrydb.com/managed-services/{id}/resize \
      -H "Content-Type: application/json" \
      -d '{"plan_name": "tier-4"}'
  3. Review slow query logs and add indexes if needed

Too Many Connections​

Symptom: FATAL: sorry, too many clients already (PostgreSQL) or similar.

  • Enable PgBouncer (port 5433) if not already in use — it multiplexes many application connections into fewer database connections
  • Reduce max_connections in client pool settings
  • Consider upgrading to a larger plan (higher plans support more connections)

Service Stuck Provisioning​

If a service stays in Provisioning for more than 10 minutes, it may have encountered an error. Contact support with the service ID. Do not delete and recreate repeatedly — this can leave orphaned resources.

Getting Help​

If you cannot resolve an issue using this guide:

  • Include the service ID and the approximate time the issue occurred
  • Include any error messages from your client
  • Contact support at support@foundrydb.com