{"record":{"id":"e169cc890e56e2ce","repo":"gastownhall/beads","slug":"hook-migration-is-blocked-s","errorCode":null,"errorMessage":"hook migration is blocked:\n- %s","messagePattern":"hook migration is blocked:\n- (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor_fix.go","lineNumber":453,"sourceCode":"}\n\nfunc fixPendingMigrations(path string) error {\n\tpending := doctor.DetectPendingMigrations(path)\n\tif len(pending) == 0 {\n\t\treturn nil\n\t}\n\n\tfor _, migration := range pending {\n\t\tswitch migration.Name {\n\t\tcase \"hooks\":\n\t\t\tplan, err := doctor.PlanHookMigration(path)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"building hook migration plan: %w\", err)\n\t\t\t}\n\n\t\t\texecPlan := buildHookMigrationExecutionPlan(plan)\n\t\t\tif len(execPlan.BlockingErrors) > 0 {\n\t\t\t\treturn fmt.Errorf(\"hook migration is blocked:\\n- %s\", strings.Join(execPlan.BlockingErrors, \"\\n- \"))\n\t\t\t}\n\n\t\t\tsummary, err := applyHookMigrationExecution(execPlan)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"applying hook migration: %w\", err)\n\t\t\t}\n\n\t\t\tfmt.Printf(\n\t\t\t\t\"  Hook migration applied: %d hook(s) written, %d artifact(s) retired, %d artifact(s) skipped\\n\",\n\t\t\t\tsummary.WrittenHookCount,\n\t\t\t\tsummary.RetiredCount,\n\t\t\t\tsummary.SkippedCount,\n\t\t\t)\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"no automatic fix available for pending migration %q\", migration.Name)\n\t\t}\n\t}\n","sourceCodeStart":435,"sourceCodeEnd":471,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor_fix.go#L435-L471","documentation":"During a pending 'hooks' migration, fixPendingMigrations builds an execution plan and checks execPlan.BlockingErrors. If any blocking errors exist, it refuses to proceed and returns this error listing them. This is a deliberate safety stop, not a crash: applying the migration would break or overwrite hooks.","triggerScenarios":"`bd fix` / `bd doctor --fix` with a pending hooks migration where buildHookMigrationExecutionPlan reports one or more BlockingErrors — e.g. a user-modified hook file that would be overwritten, unwritable hook path, or conflicting hook content.","commonSituations":"Developer customized pre-commit/post-commit hooks manually; hooks managed by another tool (husky, pre-commit framework) conflict with beads' hooks.","solutions":["Read the bullet list of blocking errors in the message and resolve each one (usually preserve or move your custom hooks)","Back up conflicting hook files and re-run `bd fix`","If another hook manager owns the hooks, configure that manager to invoke the beads hook instead of letting bd overwrite","Re-run `bd doctor` after fixing to confirm the migration can proceed"],"exampleFix":"// before: custom hook clobbered by migration\n#!/bin/sh\nexec my-linter\n// after: chain the beads hook\n#!/bin/sh\nbd hook \"$@\" || exit 1\nexec my-linter","handlingStrategy":"validation","validationCode":"plan, err := doctor.PlanHookMigration(path)\nif err == nil {\n  execPlan := buildHookMigrationExecutionPlan(plan)\n  for _, e := range execPlan.BlockingErrors { fmt.Println(\"blocking:\", e) }\n}","typeGuard":null,"tryCatchPattern":"if err := fixPendingMigrations(pending, path); err != nil {\n  if strings.HasPrefix(err.Error(), \"hook migration is blocked\") {\n    fmt.Fprintln(os.Stderr, \"Resolve blocking errors manually, then re-run.\")\n    return err // do not retry blindly\n  }\n}","preventionTips":["Don't hand-edit beads-managed hook files; chain instead of replacing","Coordinate with other hook managers (husky, pre-commit) to invoke bd hooks","Run `bd doctor` to inspect planned hook changes before applying","Keep custom hook logic in separate script files invoked from the managed hook"],"tags":["migration","hooks","doctor","blocked"],"backgroundTag":"hook-migration-blocked","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}