{"record":{"id":"7377f8638da5f771","repo":"vitessio/vitess","slug":"deadline-exceeded-waiting-for-mysqld-socket-file-t","errorCode":null,"errorMessage":"deadline exceeded waiting for mysqld socket file to appear: ","messagePattern":"deadline exceeded waiting for mysqld socket file to appear: ","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/mysqld.go","lineNumber":723,"sourceCode":"\t\t\t}\n\t\t}\n\t\tselect {\n\t\tcase <-timer.C:\n\t\t\treturn fmt.Errorf(\"timed out after %v waiting for the dba user to have the required permissions\", waitTime)\n\t\tdefault:\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t}\n\t}\n}\n\n// wait is the internal version of Wait, that takes credentials.\nfunc (mysqld *Mysqld) wait(ctx context.Context, cnf *Mycnf, params *mysql.ConnParams) error {\n\tlog.Info(fmt.Sprintf(\"Waiting for mysqld socket file (%v) to be ready...\", cnf.SocketFile))\n\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn errors.New(\"deadline exceeded waiting for mysqld socket file to appear: \" + cnf.SocketFile)\n\t\tdefault:\n\t\t}\n\n\t\t_, statErr := os.Stat(cnf.SocketFile)\n\t\tif statErr == nil {\n\t\t\t// Make sure the socket file isn't stale.\n\t\t\tconn, connErr := mysql.Connect(ctx, params)\n\t\t\tif connErr == nil {\n\t\t\t\tconn.Close()\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\tlog.Info(fmt.Sprintf(\"mysqld socket file exists, but can't connect: %v\", connErr))\n\t\t} else if !os.IsNotExist(statErr) {\n\t\t\treturn fmt.Errorf(\"can't stat mysqld socket file: %v\", statErr)\n\t\t}\n\t\ttime.Sleep(1000 * time.Millisecond)\n\t}\n}","sourceCodeStart":705,"sourceCodeEnd":741,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/mysqld.go#L705-L741","documentation":"Mysqld.wait polls for mysqld's Unix socket file to appear while starting the server. If the caller-provided context expires (deadline or cancellation) before the socket exists, this error is returned, indicating mysqld never became ready. It wraps a startup timeout rather than a connection failure per se.","triggerScenarios":"Starting mysqld via Mysqld.Wait or Mysqld.Init with a context whose deadline elapses before mysqld creates its socket file (cnf.SocketFile); mysqld crashing or hanging during startup; wrong socket path in the my.cnf used.","commonSituations":"mysqld failing to start due to corrupted data dir, bad config, port conflicts, or missing permissions on the datadir; under-provisioned CI runners making startup slower than the context deadline; misconfigured socket-file path so the file never appears where we poll.","solutions":["Check mysqld's error log (.err file in the datadir) for the underlying startup failure and fix that first","Increase the context deadline/budget passed to Wait/Init to allow slow startup on constrained machines","Verify cnf.SocketFile matches the socket path mysqld is actually configured to create","Confirm the datadir is initialized, writable, and not already in use by another mysqld instance"],"exampleFix":"// before\nctx, cancel := context.WithTimeout(ctx, 5*time.Second)\nerr := mysqld.Wait(ctx, cnf) // deadline exceeded\n// after\nctx, cancel := context.WithTimeout(ctx, 60*time.Second)\nerr := mysqld.Wait(ctx, cnf)","handlingStrategy":"retry","validationCode":"// pre-check config before starting mysqld\nif _, err := os.Stat(cnf.SocketFile); err == nil {\n    return errors.New(\"stale socket file present; clean up before starting mysqld\")\n}\nif cnf.SocketFile == \"\" {\n    return errors.New(\"socket file path not configured\")\n}","typeGuard":null,"tryCatchPattern":"ctx, cancel := context.WithTimeout(ctx, 60*time.Second)\ndefer cancel()\nif err := mysqld.Wait(ctx, cnf); err != nil {\n    if strings.Contains(err.Error(), \"deadline exceeded waiting for mysqld socket file\") {\n        log.Error(\"mysqld startup timeout; check error log\", slog.Any(\"error\", err))\n    }\n    return err\n}","preventionTips":["Give Wait/Init a generous context deadline, especially in CI","Always inspect the mysqld error log after this timeout — it usually names the real failure","Confirm socket-file path consistency between my.cnf and the Mysqld config","Ensure the datadir is initialized and not locked by another instance"],"tags":["go","mysqlctl","mysqld-startup","timeout"],"backgroundTag":"mysqld-startup-timeout","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}