vitessio/vitess · error

failed to create new db client: %s

Error message

failed to create new db client: %s

What it means

vcopier's copy-worker factory opens a dedicated DB client connection per worker (needed when parallelism > 1, so each worker queries its own @@max_allowed_packet). If newClientConnection fails, the worker cannot be created and this wrapped error is returned to the resource pool.

Source

Thrown at go/vt/vttablet/tabletmanager/vreplication/vcopier.go:750

		return err
	}
	return newVPlayer(vc.vr, settings, copyState, pos, "fastforward").play(ctx)
}

func (vc *vcopier) newCopyWorkQueue(
	parallelism int,
	workerFactory func(context.Context) (*vcopierCopyWorker, error),
) *vcopierCopyWorkQueue {
	concurrent := parallelism > 1
	return newVCopierCopyWorkQueue(concurrent, parallelism, workerFactory)
}

func (vc *vcopier) newCopyWorkerFactory(parallelism int, maxQuerySize int64) func(context.Context) (*vcopierCopyWorker, error) {
	if parallelism > 1 {
		return func(ctx context.Context) (*vcopierCopyWorker, error) {
			dbClient, err := vc.vr.newClientConnection(ctx)
			if err != nil {
				return nil, fmt.Errorf("failed to create new db client: %s", err.Error())
			}
			// Query maxQuerySize from the worker's own connection since it may
			// differ from the controller's session if @@global.max_allowed_packet
			// was changed after the controller connection was opened.
			workerMaxQuerySize := vc.vr.maxQuerySize(dbClient)
			return newVCopierCopyWorker(
				true, /* close db client */
				dbClient,
				workerMaxQuerySize,
			), nil
		}
	}
	return func(_ context.Context) (*vcopierCopyWorker, error) {
		return newVCopierCopyWorker(
			false, /* close db client */
			vc.vr.dbClient,
			maxQuerySize,
		), nil

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify vttablet can reach MySQL (check mysqld status, credentials, network) and that max_connections is not exhausted
2. Check vttablet error logs for the underlying connection error
3. Reduce copy parallelism or restart the workflow once connectivity is restored
4. Confirm the tablet's dbconfig (db_host/db_port/user) is correct

// Pre-flight: confirm MySQL connectivity from the tablet host
mysql -h <db_host> -P <db_port> -u <user> -p -e 'SELECT 1'

worker, err := vcq.workerFactory(ctx)
if err != nil {
  // check for 'failed to create new db client' root cause;
  // back off and retry after connectivity is restored
  return err
}

When it happens

Trigger: Creating the copy work queue with parallelism > 1 while the tablet cannot establish a MySQL connection: vttablet's mysqld is unreachable, credentials/auth failure, connection limit reached, or ctx already cancelled.

Common situations: MySQL restarted or max_connections exhausted; wrong db config/credentials; network partition between vttablet and mysqld; engine shutting down (ctx cancelled) while workers spin up.

Related errors

• unexpected: there are no tables to copy
• work queue is not open
• CopyAll was interrupted due to context expiration
• plan not found for table: %s, current plans are: %#v
• expecting field event first, got: %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/251b397c819d7c81. Report an issue: GitHub.