What causes "kingbase connection failed" in t8y2/dbx?

Log or inspect the per-attempt error before the loop returns so the real cause is visible instead of the generic fallback

t8y2/dbx · critical

kingbase connection failed

Error message

kingbase connection failed

What it means

This is the fallback error returned by the connection helper when the retry loop over connection attempts exhausts without establishing a session. Each attempt's real error is discarded by the loop, so this generic message masks the underlying cause (auth failure, network refusal, SSL negotiation issue).

Source

Thrown at agents/drivers/kingbase-go/main.go:528

		attempts = []string{"require", "disable"}
	}
	for index, attempt := range attempts {
		db, err := opener(cp, attempt)
		if err == nil {
			err = db.PingContext(ctx)
		}
		if err == nil {
			return db, nil
		}
		if db != nil {
			_ = db.Close()
		}
		if index == 0 && len(attempts) == 2 && shouldRetryKingbaseWithoutSSL(err) {
			continue
		}
		return nil, err
	}
	return nil, errors.New("kingbase connection failed")
}

func shouldRetryKingbaseWithoutSSL(err error) bool {
	if errors.Is(err, gokb.ErrSSLNotSupported) {
		return true
	}
	if err == nil {
		return false
	}

	// KingBase V7 can accept the SSLRequest and then reject the TLS handshake,
	// so gokb returns the TLS alert instead of ErrSSLNotSupported.
	return strings.Contains(strings.ToLower(err.Error()), "remote error: tls: handshake failure")
}

func openDBWithSSLMode(cp connectParams, sslMode string) (*sql.DB, error) {
	dsn := buildDSNWithSSLMode(cp, sslMode)
	db, err := sql.Open("kingbase", dsn)

View on GitHub (pinned to c0390bff16)

Solutions

Log or inspect the per-attempt error before the loop returns so the real cause is visible instead of the generic fallback
Verify host, port, database, and credentials in the connection parameters
Test SSL behavior: if gokb.ErrSSLNotSupported or SSL mismatch is involved, align the sslmode setting with the server capability
Confirm network reachability (ping/port probe) from the client host to the Kingbase server

Example fix

// before
		return nil, err
	}
	return nil, errors.New("kingbase connection failed")
// after
		return nil, fmt.Errorf("kingbase connection failed: %w", err)
	}
	return nil, errors.New("kingbase connection failed")

Defensive patterns

Strategy: retry

Validate before calling

connStr := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=%s", host, port, user, pw, db, sslmode); if host == "" || db == "" { return errors.New("host and dbname are required") }

Try / catch

db, err := connectKingbase(cp); if err != nil { if errors.Is(err, gokb.ErrSSLNotSupported) { /* retry with sslmode=disable */ }; return fmt.Errorf("connect: %w", err) }

Prevention

Wrap the final error with %w so the underlying per-attempt cause is preserved
Validate DSN fields (host, port, credentials, sslmode) before attempting connection
Pre-flight network connectivity checks and correct SSL settings for the server

When it happens

Trigger: All connection attempts (including the retry-without-SSL path when shouldRetryKingbaseWithoutSSL triggers on attempt 0 of 2) returned errors, so control reaches the final return.

Common situations: Wrong host/port or Kingbase server down; invalid username/password; SSL required by the driver but unsupported by the server (and vice versa); firewall or DNS problems in containerized environments.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/efa82db252969379. Report an issue: GitHub.