{"record":{"id":"3e1a4741b4620842","repo":"Budibase/budibase","slug":"unable-to-connect-error","errorCode":null,"errorMessage":"Unable to connect - ${error}","messagePattern":"Unable to connect - (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/builder/src/stores/builder/datasources.ts","lineNumber":248,"sourceCode":"\n    const datasource: Datasource = {\n      type: \"datasource\",\n      source: integration.name as SourceName,\n      config,\n      name: `${name || integration.friendlyName}${nameModifier}`,\n      projectIds,\n      plus: integration.plus && integration.name !== SourceName.REST,\n      isSQL: integration.isSQL,\n      ...(restTemplateId && { restTemplateId }),\n      ...(restTemplateVersion && { restTemplateVersion }),\n    }\n\n    const { valid, error } = await this.checkDatasourceValidity(\n      integration,\n      datasource\n    )\n    if (!valid) {\n      throw new Error(`Unable to connect - ${error}`)\n    }\n\n    const response = await API.createDatasource({\n      datasource,\n      fetchSchema: integration.plus,\n    })\n\n    return this.updateDatasourceInStore(response, { ignoreErrors: true })\n  }\n\n  async save({\n    integration,\n    datasource,\n    skipConnectionCheck,\n  }: {\n    integration: Integration\n    datasource: Datasource\n    skipConnectionCheck?: boolean","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/builder/src/stores/builder/datasources.ts#L230-L266","documentation":"datasources.create first checks connectivity with checkDatasourceValidity using the integration's verification logic. If the datasource cannot connect (valid === false) it throws 'Unable to connect - <error>', where error is the underlying reason (host unreachable, auth failed, bad URL, etc.). No datasource is created on failure.","triggerScenarios":"Creating a datasource whose target database rejects/ fails the connectivity check — wrong host/port, database down, invalid credentials, bad connection string, or network/firewall blocking the server-side connection.","commonSituations":"Typo'd host or port; SSL/TLS requirements not met; DB only reachable from certain networks; expired credentials; Docker networking where 'localhost' points at the wrong container.","solutions":["Read the appended <error> detail and fix the connection config (host, port, user, password, database).","Verify the database is running and reachable from the Budibase server/worker (not just your machine).","Test credentials with a direct client (psql/mysql client) from the server host.","Check TLS/SSL settings if the database enforces encrypted connections."],"exampleFix":"// before\n{ config: { host: \"localhost\", port: 5432 } } // server-side cannot reach localhost\n// after\n{ config: { host: \"postgres.internal\", port: 5432, user: \"bb\", password: \"...\", database: \"app\" } }","handlingStrategy":"validation","validationCode":"// validate config fields before calling create\nconst { valid, error } = await datasourceStore.checkDatasourceValidity(integration, datasource)\nif (!valid) {\n  showConnectionErrorDialog(error)\n  return\n}","typeGuard":"const hasConnectionConfig = (d: Datasource): d is Datasource & { config: { host: string; port: number } } =>\n  !!d.config && typeof (d.config as { host?: string }).host === \"string\" && typeof (d.config as { port?: number }).port === \"number\"","tryCatchPattern":"try {\n  await datasourceStore.create(datasource)\n} catch (e) {\n  if (e.message.startsWith(\"Unable to connect\")) {\n    showConnectionTroubleshooter(e.message.replace(\"Unable to connect - \", \"\"))\n    return\n  }\n  throw e\n}","preventionTips":["Test the connection with the built-in validity check before create.","Verify DB reachability from the server host (not just the browser machine).","Double-check host, port, credentials, and TLS settings; watch the appended error detail.","In containerized setups, use service hostnames instead of localhost."],"tags":["network","connectivity","datasources","validation"],"backgroundTag":"unable-to-connect","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}