{"record":{"id":"ba2d040e1a8d529d","repo":"Mintplex-Labs/anything-llm","slug":"unable-to-connect-to-engine-please-verify-your","errorCode":null,"errorMessage":"Unable to connect to ${engine}. Please verify your connection details.","messagePattern":"Unable to connect to (.+?)\\. Please verify your connection details\\.","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"server/endpoints/system.js","lineNumber":1602,"sourceCode":"          });\n        }\n\n        const {\n          validateConnection,\n        } = require(\"../utils/agents/aibitat/plugins/sql-agent/SQLConnectors\");\n        const result = await validateConnection(engine, { connectionString });\n\n        if (!result.success) {\n          return response.status(200).json({\n            success: false,\n            error: `Unable to connect to ${engine}. Please verify your connection details.`,\n          });\n        }\n\n        response.status(200).json(result);\n      } catch (error) {\n        console.error(\"SQL validation error:\", error);\n        response.status(500).json({\n          success: false,\n          error: `Unable to connect to ${engine}. Please verify your connection details.`,\n        });\n      }\n    }\n  );\n}\n\nmodule.exports = { systemEndpoints };\n","sourceCodeStart":1584,"sourceCodeEnd":1612,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/20f6d3546c1938bfea1ad304f58a592dddcc5948/server/endpoints/system.js#L1584-L1612","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\npostgresql://user:p@ss word@localhost:5432/db   # space + reserved char breaks URI parsing\n\n# after\npostgresql://user:p%40ss%20word@host.docker.internal:5432/db?sslmode=require","handlingStrategy":"try-catch","validationCode":"try { new URL(connectionString.replace(/^([a-z]+):\\/\\//, 'http://')); } catch { return setError('Malformed connection string'); }\n// then validate reachability from the same host/container before calling the endpoint","typeGuard":null,"tryCatchPattern":"try { const r = await api.post('/system/validate-sql-connection', { engine, connectionString });\n  if (!r.success) setError(`Cannot reach ${engine} — check credentials/host`); }\ncatch (e) { if (e.status === 500) setError('Validation crashed — check server logs for the driver error'); else throw e; }","preventionTips":["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."],"tags":["sql-agent","connection-string","database-connectivity"],"backgroundTag":"database-connection-failed","analyzedSha":"20f6d3546c1938bfea1ad304f58a592dddcc5948","analyzedAt":"2026-08-18T10:02:21.017Z","contentChangedAt":"2026-08-18T10:02:21.017Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}