vitessio/vitess · error

deadline exceeded waiting for mysqld socket file to appear:

Error message

deadline exceeded waiting for mysqld socket file to appear: 

What it means

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.

Source

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

			}
		}
		select {
		case <-timer.C:
			return fmt.Errorf("timed out after %v waiting for the dba user to have the required permissions", waitTime)
		default:
			time.Sleep(100 * time.Millisecond)
		}
	}
}

// wait is the internal version of Wait, that takes credentials.
func (mysqld *Mysqld) wait(ctx context.Context, cnf *Mycnf, params *mysql.ConnParams) error {
	log.Info(fmt.Sprintf("Waiting for mysqld socket file (%v) to be ready...", cnf.SocketFile))

	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)
	}
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check mysqld's error log (.err file in the datadir) for the underlying startup failure and fix that first
2. Increase the context deadline/budget passed to Wait/Init to allow slow startup on constrained machines
3. Verify cnf.SocketFile matches the socket path mysqld is actually configured to create
4. Confirm the datadir is initialized, writable, and not already in use by another mysqld instance

Example fix

// before
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
err := mysqld.Wait(ctx, cnf) // deadline exceeded
// after
ctx, cancel := context.WithTimeout(ctx, 60*time.Second)
err := mysqld.Wait(ctx, cnf)

// pre-check config before starting mysqld
if _, err := os.Stat(cnf.SocketFile); err == nil {
    return errors.New("stale socket file present; clean up before starting mysqld")
}
if cnf.SocketFile == "" {
    return errors.New("socket file path not configured")
}

ctx, cancel := context.WithTimeout(ctx, 60*time.Second)
defer cancel()
if err := mysqld.Wait(ctx, cnf); err != nil {
    if strings.Contains(err.Error(), "deadline exceeded waiting for mysqld socket file") {
        log.Error("mysqld startup timeout; check error log", slog.Any("error", err))
    }
    return err
}

When it happens

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

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

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• gave up waiting for mysqld to stop
• ReadFile cannot be called on read-write backup
• AddFile cannot be called on read-only backup
• EndBackup cannot be called on read-only backup
• AbortBackup cannot be called on read-only backup

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