{"record":{"id":"7a22616085a903fc","repo":"vitessio/vitess","slug":"can-t-stat-mysqld-socket-file-v","errorCode":null,"errorMessage":"can't stat mysqld socket file: %v","messagePattern":"can't stat mysqld socket file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/mysqld.go","lineNumber":737,"sourceCode":"\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}\n\n// Shutdown will stop the mysqld daemon that is running in the background.\n//\n// waitForMysqld: should the function block until mysqld has stopped?\n// This can actually take a *long* time if the buffer cache needs to be fully\n// flushed - on the order of 20-30 minutes.\n//\n// If a mysqlctld address is provided in a flag, Shutdown will run remotely.\nfunc (mysqld *Mysqld) Shutdown(ctx context.Context, cnf *Mycnf, waitForMysqld bool, shutdownTimeout time.Duration) error {\n\tlog.Info(\"Mysqld.Shutdown\")\n\n\t// Execute as remote action on mysqlctld if requested.\n\tif socketFile != \"\" {\n\t\tlog.Info(fmt.Sprintf(\"executing Mysqld.Shutdown() remotely via mysqlctld server: %v\", socketFile))","sourceCodeStart":719,"sourceCodeEnd":755,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/mysqld.go#L719-L755","documentation":"During mysqld startup, Vitess waits for the mysqld socket file to appear (Mysqld.wait). Each poll it stats the socket path from my.cnf. If the stat fails with an error other than 'file does not exist' (e.g. permission denied on a parent directory, stale path issues, or I/O errors), the wait loop aborts immediately with this error instead of continuing to poll. It indicates something is structurally wrong with the socket path, not merely that mysqld has not started yet.","triggerScenarios":"Mysqld.Wait (also reached via Init/Start) polls os.Stat on the mysqld socket file; stat returns an error that is not os.IsNotExist — e.g. EACCES on a directory in the socket path, ENOTDIR because a path component is a file, or ELOOP.","commonSituations":"A mysqld user lacking execute permission on the socket directory (e.g. /var/run/mysqld owned by root); a custom socket path in my.cnf whose parent directory was created as a regular file; containers with a volume mounted over part of the socket path.","solutions":["Check permissions on every directory component of the socket path (the directory mysqld writes into and its parents) and ensure the process user can traverse them.","Verify the socket path in my.cnf is valid — no path component is a regular file, and the path is not absurdly long (>108 chars for unix sockets).","Fix filesystem/mount problems on the volume holding the socket directory (disk errors, bad mounts).","If mysqld never starts, also inspect the error log tail printed by the 'failed starting mysqld in time' message to find the root cause."],"exampleFix":"// before\nsocket = /var/run/mysqld/mysqld.sock  // dir owned by root, mode 0700\n// after\nsudo mkdir -p /var/run/mysqld && sudo chown mysql:mysql /var/run/mysqld && sudo chmod 755 /var/run/mysqld","handlingStrategy":"validation","validationCode":"socketPath := filepath.Dir(cnf.SocketPath)\nif fi, err := os.Stat(socketPath); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"socket dir %s unusable: %v\", socketPath, err)\n}\nif _, err := os.Stat(cnf.SocketPath); err != nil && !os.IsNotExist(err) {\n    return fmt.Errorf(\"socket path %s unreachable: %v\", cnf.SocketPath, err)\n}","typeGuard":"func socketPathStatable(p string) bool {\n    _, err := os.Stat(p)\n    return err == nil || os.IsNotExist(err) // only these two are tolerated by wait()\n}","tryCatchPattern":"err := mysqld.Wait(ctx, cnf)\nif err != nil {\n    var perr *os.PathError\n    if errors.As(err, &perr) && !errors.Is(perr.Err, fs.ErrNotExist) {\n        // inspect/fix socket path permissions before retrying\n    }\n}","preventionTips":["Provision socket directories with correct ownership/mode in startup automation (chown mysql, chmod 755).","Keep unix socket paths under 108 characters and free of regular-file name collisions.","Health-check the socket path's directory permissions before starting mysqld."],"tags":["mysql","mysqld","startup","socket","filesystem"],"backgroundTag":"socket-path-unreachable","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}