vitessio/vitess · error

mysqld_start hook failed: %v

Error message

mysqld_start hook failed: %v

What it means

The preflight `mysqld_start` hook executed but returned an exit status other than HOOK_SUCCESS or HOOK_DOES_NOT_EXIST. startNoWait refuses to continue starting mysqld when the preflight hook reports failure; hr.String() embeds the hook's output.

Source

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

			log.Info(fmt.Sprintf("%v exit: %v", ts, err))

			// The process exited. Trigger OnTerm callbacks, unless we were canceled.
			select {
			case <-cancel:
			default:
				mysqld.mutex.Lock()
				callbacks := append([]func(){}, mysqld.onTermFuncs...)
				mysqld.mutex.Unlock()

				for _, callback := range callbacks {
					callback()
				}
			}
		}(mysqld.cancelWaitCmd)
		mysqld.mutex.Unlock()
	default:
		// hook failed, we report error
		return fmt.Errorf("mysqld_start hook failed: %v", hr.String())
	}

	// try the postflight mysqld start hook, if any
	switch hr := hook.NewHook("postflight_mysqld_start", mysqldArgs).Execute(); hr.ExitStatus {
	case hook.HOOK_SUCCESS, hook.HOOK_DOES_NOT_EXIST:
		// hook exists and worked, or does not exist, we can keep going
	default:
		// hook failed, we report error
		return fmt.Errorf("postflight_mysqld_start hook failed: %v", hr.String())
	}

	return nil
}

func cleanupLockfile(socket string, ts string) error {
	lockPath := socket + ".lock"
	pid, err := os.ReadFile(lockPath)
	if errors.Is(err, os.ErrNotExist) {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the hook output embedded in the error (hr.String()) to see why it failed
2. Run the hook script manually with the same arguments to reproduce
3. Fix the hook script or its environment/permissions
4. Remove/rename the mysqld_start hook if it's no longer needed

Example fix

// before: failing hook exits 1
#!/bin/sh
[ -d "$MYSQLDATA" ] || exit 1
// after: log and exit 0 when only advisory
#!/bin/sh
if [ ! -d "$MYSQLDATA" ]; then
  echo "WARN: data dir missing"
fi
exit 0

hr := hook.NewHook("mysqld_start", nil).Execute()
if hr.ExitStatus != hook.HOOK_SUCCESS && hr.ExitStatus != hook.HOOK_DOES_NOT_EXIST {
    return fmt.Errorf("preflight hook will fail mysqld start: %s", hr.String())
}

if err := mysqld.Start(ctx, cnf); err != nil && strings.Contains(err.Error(), "mysqld_start hook failed") {
    log.Errorf("preflight hook output: %s", err)
}

When it happens

Trigger: A script named `mysqld_start` exists in the vitess hooks directory (VTROOT/vthook or -hook_extra_env configured path) and exits non-zero during Mysqld.Start/Init.

Common situations: Operator-installed preflight hook failing a pre-start check (disk space, config validation); hook script has a bug or bad permissions; hook depends on env vars not passed in.

Related errors

• postflight_mysqld_start hook failed: %v
• process %v is still running
• ReadFile cannot be called on read-write backup
• AddFile cannot be called on read-only backup
• EndBackup cannot be called on read-only backup

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