Skip to content
DeepSQL Docs

Troubleshooting

First thing to try: collect a diagnostic bundle

Section titled “First thing to try: collect a diagnostic bundle”

When something’s wrong and you don’t know where to start, run ./scripts/diagnose.sh — it packages logs, redacted config, and reachability checks into one tarball you can attach to a support ticket.

Terminal window
cd ~/.deepsql/self-host
./scripts/diagnose.sh

See the Diagnostic bundle page for what’s in the tarball, what gets redacted, and what is not collected.

Install failures

Section titled “Install failures”

”Error: required command ‘curl’ is not installed.”

Section titled “”Error: required command ‘curl’ is not installed.””

You’re on a stripped-down image. Install curl, tar, and openssl via your package manager and re-run.

”Error: Docker Desktop is installed but the Docker daemon is not running.”

Section titled “”Error: Docker Desktop is installed but the Docker daemon is not running.””

macOS only. Start Docker Desktop from Applications, wait for the whale icon to stop animating, and re-run the installer.

”Error: cannot access Docker images from the registry.”

Section titled “”Error: cannot access Docker images from the registry.””

DeepSQL images are on ghcr.io. The host needs outbound HTTPS to ghcr.io. Most often this is a corporate proxy or VPC endpoint missing.

Installer hangs at “Waiting for Backend to become healthy”

Section titled “Installer hangs at “Waiting for Backend to become healthy””

The backend is starting but failing health checks. Check its logs:

Terminal window
docker compose -p deepsql-selfhost logs --tail=200 backend

Common causes:

  • Database password drift (the installer normally fixes this — try ./scripts/install.sh again)
  • Missing or invalid AZURE_OPENAI_KEY / AZURE_OPENAI_ENDPOINT in .env
  • Out of memory — t4g.medium is below the recommended minimum

”Error: AZURE_OPENAI_KEY is required.”

Section titled “”Error: AZURE_OPENAI_KEY is required.””

The bundled config fetch failed (network) and you don’t have a value in .env or in your environment. Either:

  • Allow outbound HTTPS to install.deepsql.ai, or
  • Export AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT before running

Install completes but UI shows “Cannot connect to backend”

Section titled “Install completes but UI shows “Cannot connect to backend””

The backend container is healthy from Docker’s perspective but the frontend can’t reach it. Check CORS_ALLOWED_ORIGINS in .env — it should include the URL you’re using to access the UI.

Runtime failures

Section titled “Runtime failures”

Frontend returns 502 after a while

Section titled “Frontend returns 502 after a while”

The backend probably crashed. Check docker compose ps and docker compose logs backend. Restart with docker compose -p deepsql-selfhost up -d backend.

Database queries to my Aurora/RDS time out

Section titled “Database queries to my Aurora/RDS time out”

Network reachability. From the DeepSQL instance:

Terminal window
nc -vz <your-db-endpoint> 5432

If this hangs, the DB security group isn’t allowing inbound from the DeepSQL security group. See Networking & Aurora/RDS access.

MCP “command not found: deepsql”

Section titled “MCP “command not found: deepsql””

npm install -g @deepsql/mcp@latest either wasn’t run, or npm’s global bin isn’t on PATH. Check:

Terminal window
npm root -g       # shows global modules path
which deepsql

Add $(npm bin -g) to your PATH or re-run the installer.

Asking for help

Section titled “Asking for help”

The fastest path to a fix:

  1. Attach a diagnostic bundle — ./scripts/diagnose.sh (see the top of this page) packages logs, config (redacted), system info, and reachability checks into one tarball.
  2. Describe what you were doing — the exact command you ran, what you expected, what happened instead.
  3. Include the installer log if the install itself failed — full terminal output, or /var/log/deepsql-install.log on CloudFormation deploys.

File issues at: https://github.com/DeepSQLAI/deepsql-self-host/issues