Unable to connect to ${engine}. Please verify your connectio

Error message

Unable to connect to ${engine}. Please verify your connection details.

What it means

Returned by POST /system/validate-sql-connection both when validateConnection(engine, {connectionString}) reports failure (200 with success:false) and when it throws (500) — the message is the generic 'Unable to connect to <engine>. Please verify your connection details.' Causes include wrong credentials, unreachable host/firewall, unsupported engine name, malformed connection string, or a driver loading error inside SQLConnectors.

Source

Thrown at server/endpoints/system.js:1602

          });
        }

        const {
          validateConnection,
        } = require("../utils/agents/aibitat/plugins/sql-agent/SQLConnectors");
        const result = await validateConnection(engine, { connectionString });

        if (!result.success) {
          return response.status(200).json({
            success: false,
            error: `Unable to connect to ${engine}. Please verify your connection details.`,
          });
        }

        response.status(200).json(result);
      } catch (error) {
        console.error("SQL validation error:", error);
        response.status(500).json({
          success: false,
          error: `Unable to connect to ${engine}. Please verify your connection details.`,
        });
      }
    }
  );
}

module.exports = { systemEndpoints };

View on GitHub (pinned to 20f6d3546c)

Solutions

Verify the same connection string works from the same network context: run the validation from inside the container/host the server runs on (psql/mysql CLI).
URL-encode special characters in the userinfo portion of the URI.
Confirm the engine key matches exactly what SQLConnectors supports (see server/utils/agents/aibitat/plugins/sql-agent/SQLConnectors).
For Docker, use service names or host.docker.internal instead of localhost.
Check server log 'SQL validation error:' when the response is 500 — that variant carries a thrown exception, e.g. a missing driver.

Example fix

# before
postgresql://user:p@ss word@localhost:5432/db   # space + reserved char breaks URI parsing

# after
postgresql://user:p%40ss%20word@host.docker.internal:5432/db?sslmode=require

Defensive patterns

Strategy: try-catch

Validate before calling

try { new URL(connectionString.replace(/^([a-z]+):\/\//, 'http://')); } catch { return setError('Malformed connection string'); }
// then validate reachability from the same host/container before calling the endpoint

Try / catch

try { const r = await api.post('/system/validate-sql-connection', { engine, connectionString });
  if (!r.success) setError(`Cannot reach ${engine} — check credentials/host`); }
catch (e) { if (e.status === 500) setError('Validation crashed — check server logs for the driver error'); else throw e; }

Prevention

URL-encode special characters in the connection-string userinfo.
Validate from the same network namespace the server runs in (container, not laptop).
Use exact engine keys from SQLConnectors; unknown engines fail with this generic message.
For cloud DBs include SSL params (sslmode=require) up front.

When it happens

Trigger: Bad password in the connection string; DB host not reachable from the container (NAT/VPN/firewall); engine typo like 'postgresql' where the connector registry expects 'postgres'; missing driver dependency for the engine; TLS/SSL requirements rejected by the server.

Common situations: Validating a connector from a Docker container where 'localhost' points at the container itself instead of the host DB; special characters in the password not URL-encoded within the URI; cloud DBs requiring SSL enforced client-side.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@20f6d3546c (2026-08-18). Data as JSON: /api/errors/ba2d040e1a8d529d. Report an issue: GitHub.