bytebase/bytebase · error

failed to connect to OpenSearch

Error message

failed to connect to OpenSearch

What it means

This is the fallback wrap applied in Ping when the Info request fails with any error that is neither 401/403 nor 404 — i.e. the driver could not obtain cluster info for an unclassified reason. The original error is preserved as the cause; the message names the OpenSearch connection attempt.

Source

Thrown at backend/plugin/db/elasticsearch/elasticsearch.go:349

		ctx := context.Background()
		info, err := d.opensearchAPI.Info(ctx, &opensearchapi.InfoReq{})
		if err != nil {
			// Check if it's an authentication or connection issue
			errStr := err.Error()
			if strings.Contains(errStr, "401") || strings.Contains(errStr, "403") {
				// Check if role assumption was attempted
				if d.config.DataSource.GetAwsCredential() != nil &&
					d.config.DataSource.GetAwsCredential().RoleArn != "" {
					return errors.Errorf("authentication failed: unable to assume role %s: %v",
						d.config.DataSource.GetAwsCredential().RoleArn, err)
				}
				return errors.Errorf("authentication failed (consider using cross-account role if accessing different AWS account): %v", err)
			}
			if strings.Contains(errStr, "404") {
				return errors.Errorf("endpoint not found (check if path is correct): %v", err)
			}
			// For any other error, return the full error
			return errors.Wrapf(err, "failed to connect to OpenSearch")
		}
		if info == nil || info.Version.Number == "" {
			return errors.New("invalid response from server")
		}
		return nil
	}

	// Use Elasticsearch client
	if d.typedClient != nil {
		res, err := d.typedClient.Ping()
		if err != nil {
			return errors.Wrapf(err, "failed to ping db")
		}
		defer res.Body.Close()
		if res.IsError() {
			return errors.Errorf("ping failed: %s", res.String())
		}
		return nil

View on GitHub (pinned to 1870550677)

Solutions

1. Read the wrapped cause to identify whether it is DNS, connection refused, TLS, or an HTTP 5xx error.
2. Verify network reachability: same VPC/security group rules allow traffic to the domain's port from the Bytebase host.
3. Confirm the TLS certificate is valid (or configured CA) and the scheme matches the listener.
4. If a proxy returns 5xx, check the upstream domain health in the AWS/OpenSearch console.

const reachable = await fetch(dataSource.address + "/", { signal: AbortSignal.timeout(5000) }).then(r => r.ok).catch(() => false);
if (!reachable) throw new Error("OpenSearch endpoint unreachable from this host");

try {
  await driver.ping(ctx);
} catch (e) {
  if (String(e).includes("failed to connect to OpenSearch")) {
    // inspect e.cause for DNS/TLS/timeout and retry with backoff for transient 5xx
  }
  throw e;
}

When it happens

Trigger: Ping() -> opensearchAPI.Info() returns an error whose string does not contain "401", "403", or "404": network timeouts, DNS failures, connection refused, TLS handshake errors, 5xx responses, or malformed responses from the server.

Common situations: Domain is not reachable from the network/VPC (security group blocks the port); DNS typo in host; expired TLS certificate causing handshake failure; server returning 502/503 from a proxy; request timeout due to a cold/serverless domain.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• failed to ping db
• failed to send HTTP request via OpenSearch client
• failed to get index settings
• failed to list indices
• failed to ping CosmosDB emulator

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/85b9ea149ca2b628. Report an issue: GitHub.