windmill-labs/windmill · error

Could not connect to the database

Error message

Could not connect to the database

What it means

When the postgresql connection-check job does complete but reports success=false, the probe throws either the error message returned by the script (done.result?.error?.message) or the fallback 'Could not connect to the database'. It means a worker ran the check and Postgres actively refused/failed the connection.

Source

Thrown at frontend/src/lib/components/workspaceSettings/datatableProbe.ts:88

		timeoutCode: async () => {
			await JobService.cancelQueuedJob({
				workspace,
				id: job,
				requestBody: { reason: 'The connection check did not start' }
			}).catch(() => {})
		},
		interval: 500,
		timeout
	})

	if (!completed) {
		throw new Error(
			'The connection check did not run. Is a worker listening to the postgresql tag available?'
		)
	}
	const done = completed as { success: boolean; result?: any }
	if (!done.success) {
		throw new Error(done.result?.error?.message ?? 'Could not connect to the database')
	}

	const row: Row = (Array.isArray(done.result) ? done.result[0] : done.result) ?? {}
	// Suggested only where the privilege is actually missing; Postgres returns NULL for a
	// statement it could not name, which is the case where no grant would help anyway.
	const suggested_grants = [
		row.can_create_table ? undefined : (row.grant_schema ?? undefined),
		row.can_create_schema ? undefined : (row.grant_database ?? undefined)
	].filter((s): s is string => !!s)

	return {
		user: row.usr ?? '',
		schema: row.sch ?? null,
		can_create_table: !!row.can_create_table,
		can_create_schema: !!row.can_create_schema,
		migrations_table_exists: !!row.has_migrations_table,
		suggested_grants,
		suggested_search_path: row.sch ? undefined : (row.fix_search_path ?? undefined)

View on GitHub (pinned to e474e8803c)

Solutions

1. Read the underlying message when present (done.result.error.message) — it names the actual Postgres failure
2. Verify host, port, database, user and password in the resource; test with `psql` from a machine that shares the worker's network
3. Check Postgres server logs and pg_hba.conf / listen_addresses for rejected connections
4. Confirm network reachability from the worker (firewalls, security groups, VPC peering, TLS requirements)

Example fix

// before
{ database: 'db', host: 'localhost', port: 5432 }  // worker cannot see 'localhost'
// after
{ database: 'db', host: 'postgres.internal', port: 5432 }  // reachable from the worker

// validate inputs before probing
if (!host || !port || !db || !user || !password) throw new Error('Fill all connection fields before testing')

try {
  await probeDatatableConnection(...)
} catch (e) {
  const msg = e?.message ?? ''
  if (/password authentication failed/i.test(msg)) { /* fix credentials */ }
  else if (/connection refused|could not connect/i.test(msg)) { /* fix host/port/network */ }
}

When it happens

Trigger: The connection-check script runs on a postgresql-tagged worker and its result has success=false with no parseable error.message — bad host/port, wrong credentials, TLS issues, unreachable database, or the script result shape differs from expected.

Common situations: Typo in database host/port or database name; wrong username/password; Postgres not accepting remote connections (pg_hba.conf/listen_addresses); firewall or VPC blocking the worker's egress; expired credentials.

Related errors

• Error fetching row: {:?}
• ApiError with mapped HTTP status message (e.g. "Not Found",
• Generic Error: status: ${errorStatus}; status text: ${errorS
• Dependency generation failed: ${queueResponse.status} ${queu
• Failed to poll dependencies job ${jobId}: ${e?.message ?? e}

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/6cca615556325bd1. Report an issue: GitHub.