vitessio/vitess · error

can't stat mysqld socket file: %v

Error message

can't stat mysqld socket file: %v

What it means

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.

Source

Thrown at go/vt/mysqlctl/mysqld.go:737

	for {
		select {
		case <-ctx.Done():
			return errors.New("deadline exceeded waiting for mysqld socket file to appear: " + cnf.SocketFile)
		default:
		}

		_, statErr := os.Stat(cnf.SocketFile)
		if statErr == nil {
			// Make sure the socket file isn't stale.
			conn, connErr := mysql.Connect(ctx, params)
			if connErr == nil {
				conn.Close()
				return nil
			}
			log.Info(fmt.Sprintf("mysqld socket file exists, but can't connect: %v", connErr))
		} else if !os.IsNotExist(statErr) {
			return fmt.Errorf("can't stat mysqld socket file: %v", statErr)
		}
		time.Sleep(1000 * time.Millisecond)
	}
}

// Shutdown will stop the mysqld daemon that is running in the background.
//
// waitForMysqld: should the function block until mysqld has stopped?
// This can actually take a *long* time if the buffer cache needs to be fully
// flushed - on the order of 20-30 minutes.
//
// If a mysqlctld address is provided in a flag, Shutdown will run remotely.
func (mysqld *Mysqld) Shutdown(ctx context.Context, cnf *Mycnf, waitForMysqld bool, shutdownTimeout time.Duration) error {
	log.Info("Mysqld.Shutdown")

	// Execute as remote action on mysqlctld if requested.
	if socketFile != "" {
		log.Info(fmt.Sprintf("executing Mysqld.Shutdown() remotely via mysqlctld server: %v", socketFile))

View on GitHub (pinned to 01a25a7d17)

Solutions

1. 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.
2. 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).
3. Fix filesystem/mount problems on the volume holding the socket directory (disk errors, bad mounts).
4. If mysqld never starts, also inspect the error log tail printed by the 'failed starting mysqld in time' message to find the root cause.

Example fix

// before
socket = /var/run/mysqld/mysqld.sock  // dir owned by root, mode 0700
// after
sudo mkdir -p /var/run/mysqld && sudo chown mysql:mysql /var/run/mysqld && sudo chmod 755 /var/run/mysqld

socketPath := filepath.Dir(cnf.SocketPath)
if fi, err := os.Stat(socketPath); err != nil || !fi.IsDir() {
    return fmt.Errorf("socket dir %s unusable: %v", socketPath, err)
}
if _, err := os.Stat(cnf.SocketPath); err != nil && !os.IsNotExist(err) {
    return fmt.Errorf("socket path %s unreachable: %v", cnf.SocketPath, err)
}

func socketPathStatable(p string) bool {
    _, err := os.Stat(p)
    return err == nil || os.IsNotExist(err) // only these two are tolerated by wait()
}

err := mysqld.Wait(ctx, cnf)
if err != nil {
    var perr *os.PathError
    if errors.As(err, &perr) && !errors.Is(perr.Err, fs.ErrNotExist) {
        // inspect/fix socket path permissions before retrying
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to initialize mysqld: %v
• mysqld_shutdown hook failed: %v
• %v: %w, output: %v
• failed to initialize clone support: %v
• can't read init-db-sql-file (%v): %v

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