What causes "failed to create vcopier worker: %s" in vitessio/vitess?

Look for the wrapped inner error (e.g. 'failed to create new db client') for the root cause

failed to create vcopier worker: %s

Error message

failed to create vcopier worker: %s

What it means

The copy work queue's ResourcePool factory creates each vcopierCopyWorker by calling the user-supplied workerFactory (which opens a DB connection). Any failure there is wrapped as 'failed to create vcopier worker'. This is the pool-level wrapper around lower-level creation failures such as error 1395.

Source

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

// open the work queue. The provided arguments are used to generate
// statements for inserting rows and copy state.
func (vcq *vcopierCopyWorkQueue) open(
	copyStateInsert *sqlparser.ParsedQuery,
	pkfields []*querypb.Field,
	tablePlan *TablePlan,
) {
	if vcq.isOpen {
		return
	}

	poolCapacity := int(math.Max(float64(vcq.maxDepth), 1))
	vcq.workerPool = pools.NewResourcePool(
		/* factory */
		func(ctx context.Context) (pools.Resource, error) {
			worker, err := vcq.workerFactory(ctx)
			if err != nil {
				return nil, fmt.Errorf(
					"failed to create vcopier worker: %s",
					err.Error(),
				)
			}
			worker.open(copyStateInsert, pkfields, tablePlan)
			return worker, nil
		},
		poolCapacity, /* initial capacity */
		poolCapacity, /* max capacity */
		0,            /* idle timeout */
		0,            /* max lifetime */
		nil,          /* log wait */
		nil,          /* refresh check */
		0,            /* refresh interval */
	)

	vcq.isOpen = true
}

View on GitHub (pinned to 01a25a7d17)

Solutions

Look for the wrapped inner error (e.g. 'failed to create new db client') for the root cause
Fix MySQL connectivity/credentials, then restart the copy phase
Reduce parallelism so fewer simultaneous worker connections are needed
Retry after the database is healthy

Defensive patterns

Strategy: retry

Validate before calling

// Verify DB connectivity and credentials before opening the copy queue
mysql -h <db_host> -P <db_port> -u <user> -p -e 'SELECT 1'

Try / catch

worker, err := pool.Get(ctx)
if err != nil {
  if strings.Contains(err.Error(), "failed to create vcopier worker") {
    // inspect wrapped cause (db client creation) and retry after fix
  }
  return err
}

Prevention

Reduce parallelism if the database rejects concurrent connections
Ensure the engine is not shutting down while workers are created
Watch logs for the inner 'failed to create new db client' cause

When it happens

Trigger: ResourcePool factory invoked during queue open or worker replenishment while workerFactory fails — typically newClientConnection error, or a subsequent worker.open/setup failure.

Common situations: MySQL unreachable or out of connections during parallel copy startup; controller session settings invalid; engine shutdown racing worker creation.

Related errors

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