#Weird error self-hosting

11 messages · Page 1 of 1 (latest)

cloud furnaceBOT
#

Hi @craggy breach. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

That specific error (cluster url username must be set) is coming from the database connection string your backend is using.

From a very similar Discord thread, this error was traced to the Postgres connection URL not having a proper username in it. [Self host thread]

In the self‑hosting docs, when using Postgres you’re expected to set a full connection URL via DATABASE_URL / POSTGRES_URL, e.g.: [Option 3 docs]

DATABASE_URL=postgresql://user:[email protected]
# with a database named convex_self_hosted

And in the example Docker config from that thread, they had:

- DATABASE_URL=${CONVEX_DATABASE_URL:-postgresql://postgres:postgres@localhost:5432}
- POSTGRES_URL=${POSTGRES_URL:-postgresql://postgres:postgres@localhost:5432}

So to debug:

  1. Check what URL is actually being passed into the container:

    • Run docker compose config and look at the resolved DATABASE_URL / POSTGRES_URL.
    • Make sure it’s not empty and that it includes a username (the user part in postgresql://user:password@host:port).

  2. Prefer POSTGRES_URL over DATABASE_URL
    The log you pasted shows DATABASE_URL is deprecated. The current recommendation is to set:

    environment:
  - POSTGRES_URL=postgresql://postgres:postgres@convex-postgres:5432

    (Note: use the Postgres service name from your docker-compose.yml instead of localhost so the backend can reach it from inside the Docker network.) [Option 3 docs]

#
  1. Ensure the DB exists and is reachable
    The docs expect a database named convex_self_hosted when using Postgres. [Option 3 docs]
    Your URL should look like:
    POSTGRES_URL=postgresql://postgres:postgres@convex-postgres:5432/convex_self_hosted

If you share your docker-compose.yml (with secrets redacted), you can compare it directly to the example in the self‑hosting README and the Discord snippet above to make sure the env vars line up. [Self-host README; Self host thread]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@craggy breach Kapa.ai is still learning and improving, please let me know how I did by reacting below.

#

Let me check the knowledge base for you again. One moment! :books:

#

The error is coming from how the Convex backend is connecting to Postgres: it’s trying to use TLS, but your Postgres server is running without TLS:

error performing TLS handshake: server does not support TLS

In the official self‑hosting docs, the Postgres connection is configured via POSTGRES_URL (or the now‑deprecated DATABASE_URL) as a standard connection string, e.g.: [Option 3 docs]

POSTGRES_URL=postgresql://user:[email protected]

However, the knowledge sources don’t document any flags or URL parameters to force TLS off or choose TLS mode; they only say to provide a normal Postgres URL and ensure a convex_self_hosted database exists. [Option 3 docs]

Because of that, I can’t confidently tell you how to switch the Convex backend to a non‑TLS connection from the docs alone.

What you can do, based on the docs:

  1. Double‑check your POSTGRES_URL / DATABASE_URL
    Make sure it’s set and points at your Postgres instance, e.g.:

    environment:
  - POSTGRES_URL=postgresql://postgres:postgres@convex-postgres:5432/convex_self_hosted

    where convex-postgres is the service name from your docker-compose.yml. [Self-host README; Option 3 docs]

#

  1. Compare against the official Docker examples
    The self‑hosting README and the self-hosted/docker setup show the expected environment variables and patterns; aligning your compose file with those is the safest path. [Self-host README; Self-hosting setup]

  2. If you’re using a managed Postgres (like Neon)
    The docs explicitly mention Neon and only require setting DATABASE_URL / POSTGRES_URL and creating the convex_self_hosted DB; they don’t mention TLS toggles. [Option 3 docs]

Given the lack of TLS‑specific configuration in the knowledge sources, the best next step is to:

  • Post your docker-compose.yml (with secrets redacted) and the exact POSTGRES_URL you’re using in the #self-hosted channel on Discord, which is where the Convex team directs self‑hosting questions. [Self-host README; Questions & contributions]

That way they can confirm whether the backend currently always expects TLS for external Postgres, or if there’s a documented way (not present in these sources) to connect to a non‑TLS Postgres instance.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@craggy breach Kapa.ai is still learning and improving, please let me know how I did by reacting below.

#

Let me check the knowledge base for you again. One moment! :books:

#

The knowledge sources don’t describe TLS options or sslmode handling for POSTGRES_URL, so I can’t say for sure how ?sslmode=disable is interpreted by the backend. I’ll stick to what is documented and what’s clearly off in your compose file.

1. Your healthcheck DB name is wrong

Your Postgres service:

db:
  image: postgres
  volumes:
    - db_data:/var/lib/postgresql
  environment:
    POSTGRES_PASSWORD: password
    POSTGRES_DB: convex_self_hosted
  healthcheck:
    test: [ "CMD-SHELL", "pg_isready", "-d", "db_prod" ]

You create convex_self_hosted but the healthcheck probes db_prod. The self‑hosting docs explicitly say to create a DB named convex_self_hosted when using Postgres. [Option 3]

Change the healthcheck to:

healthcheck:
  test: [ "CMD-SHELL", "pg_isready", "-d", "convex_self_hosted" ]

2. Use the documented Postgres URL shape

Docs show:

DATABASE_URL=postgresql://user:[email protected]
# and then create a DB called convex_self_hosted
``` [[Option 3](<https://stack.convex.dev/self-hosted-develop-and-deploy#option-3-docker-containers-on-a-remote-server>)]

Your backend env:

```yaml
- POSTGRES_URL=postgresql://postgres:password@db:5432?sslmode=disable

Two issues relative to the docs:

  1. No database name in the URL.
  2. sslmode=disable is not mentioned anywhere in the docs, so behavior is unclear.

To align with the docs, try:

environment:
  - POSTGRES_URL=postgresql://postgres:password@db:5432/convex_self_hosted

(Use the service name db as you already do; that’s correct for Docker networking.)

3. Prefer POSTGRES_URL and drop DATABASE_URL

#

You already set POSTGRES_URL, which is the recommended variable; DATABASE_URL is deprecated. [Option 3]

Right now you have:

- DATABASE_URL
- POSTGRES_URL=postgresql://postgres:password@db:5432?sslmode=disable

If DATABASE_URL is set in your shell, it may conflict. To be safe, either:

  • Unset DATABASE_URL in your environment before docker compose up, or
  • Remove - DATABASE_URL from the compose file so only POSTGRES_URL is used.

4. If TLS errors persist

The TLS handshake error you saw:

error performing TLS handshake: server does not support TLS

is not covered in the docs, and there’s no documented flag/env to force non‑TLS connections. The self‑hosting README explicitly points self‑hosting questions to the #self-hosted Discord channel. [Self-host README]

If, after:

  • fixing the DB name in the healthcheck,
  • using postgresql://postgres:password@db:5432/convex_self_hosted,
  • and ensuring DATABASE_URL isn’t conflicting,

you still get TLS errors, the next step (per the docs) is to post this compose file and the exact error in #self-hosted on Discord so the team can confirm current TLS behavior for POSTGRES_URL. [Questions & contributions]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: