{"record":{"id":"0f0e8970c011dfe3","repo":"vitessio/vitess","slug":"mysqld-start-hook-failed-v","errorCode":null,"errorMessage":"mysqld_start hook failed: %v","messagePattern":"mysqld_start hook failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/mysqld.go","lineNumber":599,"sourceCode":"\t\t\tlog.Info(fmt.Sprintf(\"%v exit: %v\", ts, err))\n\n\t\t\t// The process exited. Trigger OnTerm callbacks, unless we were canceled.\n\t\t\tselect {\n\t\t\tcase <-cancel:\n\t\t\tdefault:\n\t\t\t\tmysqld.mutex.Lock()\n\t\t\t\tcallbacks := append([]func(){}, mysqld.onTermFuncs...)\n\t\t\t\tmysqld.mutex.Unlock()\n\n\t\t\t\tfor _, callback := range callbacks {\n\t\t\t\t\tcallback()\n\t\t\t\t}\n\t\t\t}\n\t\t}(mysqld.cancelWaitCmd)\n\t\tmysqld.mutex.Unlock()\n\tdefault:\n\t\t// hook failed, we report error\n\t\treturn fmt.Errorf(\"mysqld_start hook failed: %v\", hr.String())\n\t}\n\n\t// try the postflight mysqld start hook, if any\n\tswitch hr := hook.NewHook(\"postflight_mysqld_start\", mysqldArgs).Execute(); hr.ExitStatus {\n\tcase hook.HOOK_SUCCESS, hook.HOOK_DOES_NOT_EXIST:\n\t\t// hook exists and worked, or does not exist, we can keep going\n\tdefault:\n\t\t// hook failed, we report error\n\t\treturn fmt.Errorf(\"postflight_mysqld_start hook failed: %v\", hr.String())\n\t}\n\n\treturn nil\n}\n\nfunc cleanupLockfile(socket string, ts string) error {\n\tlockPath := socket + \".lock\"\n\tpid, err := os.ReadFile(lockPath)\n\tif errors.Is(err, os.ErrNotExist) {","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/mysqld.go#L581-L617","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the hook output embedded in the error (hr.String()) to see why it failed","Run the hook script manually with the same arguments to reproduce","Fix the hook script or its environment/permissions","Remove/rename the mysqld_start hook if it's no longer needed"],"exampleFix":"// before: failing hook exits 1\n#!/bin/sh\n[ -d \"$MYSQLDATA\" ] || exit 1\n// after: log and exit 0 when only advisory\n#!/bin/sh\nif [ ! -d \"$MYSQLDATA\" ]; then\n  echo \"WARN: data dir missing\"\nfi\nexit 0","handlingStrategy":"validation","validationCode":"hr := hook.NewHook(\"mysqld_start\", nil).Execute()\nif hr.ExitStatus != hook.HOOK_SUCCESS && hr.ExitStatus != hook.HOOK_DOES_NOT_EXIST {\n    return fmt.Errorf(\"preflight hook will fail mysqld start: %s\", hr.String())\n}","typeGuard":null,"tryCatchPattern":"if err := mysqld.Start(ctx, cnf); err != nil && strings.Contains(err.Error(), \"mysqld_start hook failed\") {\n    log.Errorf(\"preflight hook output: %s\", err)\n}","preventionTips":["Test hook scripts in the vthook directory with the same args vitess passes","Make hooks exit 0 for advisory-only checks","Audit hooks installed on every tablet host","Keep hooks idempotent and fast"],"tags":["hooks","mysqlctl","startup"],"backgroundTag":"hook-execution-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}