Known errors

This page documents real issues you may hit, with the exact symptom and the fix.

Bun may fail to connect to Postgres/Redis over self-signed TLS

This is a possible issue, not a guaranteed one — you may or may not hit it depending on the certificate and the TLS endpoint. It is worth knowing about because it is easy to misdiagnose.

Symptom. The gateway (or db:migrate) fails to reach Postgres or Redis when the connection uses TLS with a self-signed certificate — most often a database or cache exposed by Coolify, Dokploy, or a hand-rolled Docker setup over a public port. When it happens, Bun's TLS stack reports:

error:1000009a:SSL routines:OPENSSL_internal:HANDSHAKE_FAILURE_ON_CLIENT_HELLO
(ERR_SSL_HANDSHAKE_FAILURE_ON_CLIENT_HELLO)

It fails at the ClientHello — before any certificate verification — so sslmode=require, rejectUnauthorized: false and NODE_TLS_REJECT_UNAUTHORIZED=0 make no difference.

Cause. Unified Gateway runs on the Bun runtime, whose bundled TLS library (BoringSSL) can reject the handshake against some self-signed endpoints (reproduced with Coolify's self-signed Postgres and Redis certificates; it does not necessarily affect every self-signed setup). The same URLs connect fine under Node/OpenSSL and openssl s_client, and Bun's TLS works against public-CA endpoints (OpenAI, managed databases) — so when it does occur it is specific to self-signed certificates, not TLS in general.

Fix — keep TLS out of Bun's path. Pick one:

• Private network, no TLS (recommended for self-hosting). Run the gateway in the same private network as Postgres/Redis and connect over plaintext: postgres://… (no sslmode) and redis://… (not rediss://). On an isolated network the link is protected by network isolation, not TLS. This is what every Docker Compose deployment does out of the box.
• Managed database with a public-CA certificate. Providers like Neon, Aiven, Supabase (Postgres) and Upstash (Redis) present publicly-trusted certificates, which Bun connects to without issue. See Setup → Managed database and Redis.
• TLS-terminating proxy (stunnel). If you must reach a self-signed endpoint over an untrusted network from your own machine, run a local stunnel that speaks TLS upstream and exposes plaintext on localhost, then point the gateway at localhost.

Self-host note. Coolify and Dokploy expose standalone databases with a self-signed certificate. The simplest fix is to disable SSL on both the Postgres and Redis services (uncheck Enable SSL) and connect over the private network with postgres://… and redis://… (no sslmode, not rediss://). Inside the platform's private network this is both simpler and faster than TLS. See the platform pages under Deployment.

Security note

Plaintext is safe on a private network: the gateway and database share an isolated bridge that never touches the internet. It is not safe across the public internet — credentials and data travel unencrypted and an on-path attacker can read them. If your database is only reachable over a public port, use a managed provider with a public-CA certificate, or an stunnel tunnel, instead of plaintext.