gastownhall/beads · error

applying hook migration: %w

Error message

applying hook migration: %w

What it means

fixPendingMigrations wraps failures from applyHookMigrationExecution when actually writing hooks or retiring artifacts. The %w cause describes the concrete failure (write permission, disk error, etc.). It occurs after the plan passed blocking-error checks.

Source

Thrown at cmd/bd/doctor_fix.go:458

		return nil
	}

	for _, migration := range pending {
		switch migration.Name {
		case "hooks":
			plan, err := doctor.PlanHookMigration(path)
			if err != nil {
				return fmt.Errorf("building hook migration plan: %w", err)
			}

			execPlan := buildHookMigrationExecutionPlan(plan)
			if len(execPlan.BlockingErrors) > 0 {
				return fmt.Errorf("hook migration is blocked:\n- %s", strings.Join(execPlan.BlockingErrors, "\n- "))
			}

			summary, err := applyHookMigrationExecution(execPlan)
			if err != nil {
				return fmt.Errorf("applying hook migration: %w", err)
			}

			fmt.Printf(
				"  Hook migration applied: %d hook(s) written, %d artifact(s) retired, %d artifact(s) skipped\n",
				summary.WrittenHookCount,
				summary.RetiredCount,
				summary.SkippedCount,
			)
		default:
			return fmt.Errorf("no automatic fix available for pending migration %q", migration.Name)
		}
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause and fix it (usually chmod/chown .git/hooks or free disk space)
2. Ensure .git/hooks is writable by the current user: `ls -la .git/hooks`
3. Re-run `bd fix` — planning and application are re-done atomically per migration
4. If partially applied, run `bd doctor` to see remaining pending migrations and re-fix

Example fix

// before
sudo bd fix   # hooks written as root
// after
bd fix        # run as the repo owner so .git/hooks stays writable

info, err := os.Stat(hooksDir)
if err != nil || !info.IsDir() || unix.Access(hooksDir, unix.W_OK) != nil {
  return fmt.Errorf(".git/hooks not writable")
}

if err := fixPendingMigrations(pending, path); err != nil {
  if strings.Contains(err.Error(), "applying hook migration") {
    // check permissions/disk, then re-run: apply is re-planned safely
    return err
  }
}

When it happens

Trigger: `bd fix` with a pending hooks migration where applyHookMigrationExecution fails mid-apply: hook file not writable, git dir changed between plan and apply, or filesystem error writing hook content.

Common situations: Read-only .git/hooks (root-owned files after sudo usage), disk full, or hooks directory deleted/replaced after planning (TOCTOU between plan and apply).

Related errors

• building hook migration plan: %w
• hook migration is blocked: - %s
• failed to create output file: %w
• scanning artifacts at %s: %w
• unable to read plugin file: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a1ffa6cba64bbe83. Report an issue: GitHub.