{"record":{"id":"251b397c819d7c81","repo":"vitessio/vitess","slug":"failed-to-create-new-db-client-s","errorCode":null,"errorMessage":"failed to create new db client: %s","messagePattern":"failed to create new db client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vttablet/tabletmanager/vreplication/vcopier.go","lineNumber":750,"sourceCode":"\t\treturn err\n\t}\n\treturn newVPlayer(vc.vr, settings, copyState, pos, \"fastforward\").play(ctx)\n}\n\nfunc (vc *vcopier) newCopyWorkQueue(\n\tparallelism int,\n\tworkerFactory func(context.Context) (*vcopierCopyWorker, error),\n) *vcopierCopyWorkQueue {\n\tconcurrent := parallelism > 1\n\treturn newVCopierCopyWorkQueue(concurrent, parallelism, workerFactory)\n}\n\nfunc (vc *vcopier) newCopyWorkerFactory(parallelism int, maxQuerySize int64) func(context.Context) (*vcopierCopyWorker, error) {\n\tif parallelism > 1 {\n\t\treturn func(ctx context.Context) (*vcopierCopyWorker, error) {\n\t\t\tdbClient, err := vc.vr.newClientConnection(ctx)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to create new db client: %s\", err.Error())\n\t\t\t}\n\t\t\t// Query maxQuerySize from the worker's own connection since it may\n\t\t\t// differ from the controller's session if @@global.max_allowed_packet\n\t\t\t// was changed after the controller connection was opened.\n\t\t\tworkerMaxQuerySize := vc.vr.maxQuerySize(dbClient)\n\t\t\treturn newVCopierCopyWorker(\n\t\t\t\ttrue, /* close db client */\n\t\t\t\tdbClient,\n\t\t\t\tworkerMaxQuerySize,\n\t\t\t), nil\n\t\t}\n\t}\n\treturn func(_ context.Context) (*vcopierCopyWorker, error) {\n\t\treturn newVCopierCopyWorker(\n\t\t\tfalse, /* close db client */\n\t\t\tvc.vr.dbClient,\n\t\t\tmaxQuerySize,\n\t\t), nil","sourceCodeStart":732,"sourceCodeEnd":768,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vttablet/tabletmanager/vreplication/vcopier.go#L732-L768","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify vttablet can reach MySQL (check mysqld status, credentials, network) and that max_connections is not exhausted","Check vttablet error logs for the underlying connection error","Reduce copy parallelism or restart the workflow once connectivity is restored","Confirm the tablet's dbconfig (db_host/db_port/user) is correct"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight: confirm MySQL connectivity from the tablet host\nmysql -h <db_host> -P <db_port> -u <user> -p -e 'SELECT 1'","typeGuard":null,"tryCatchPattern":"worker, err := vcq.workerFactory(ctx)\nif err != nil {\n  // check for 'failed to create new db client' root cause;\n  // back off and retry after connectivity is restored\n  return err\n}","preventionTips":["Monitor mysqld health and max_connections headroom","Validate tablet dbconfig credentials before starting workflows","Bound copy parallelism to what the DB can accept","Use generous ctx timeouts for copy startup"],"tags":["vreplication","vcopier","database-connection","parallel-copy"],"backgroundTag":"database-connection-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}