gastownhall/beads · error

no automatic fix available for pending migration %q

Error message

no automatic fix available for pending migration %q

What it means

fixPendingMigrations handles a known set of pending migrations via a switch; only 'hooks' is implemented. Any other migration name falls into the default branch and returns this error, meaning the migration exists in the doctor's data but has no automatic fixer.

Source

Thrown at cmd/bd/doctor_fix.go:468

			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. Upgrade bd to the latest version (`bd doctor` shows the version; update if outdated) so a fixer for this migration exists
2. Check the migration name in the message against `bd doctor` output and follow its manual instructions
3. If you intentionally downgraded, either re-upgrade or clear the stale pending-migration state per docs
4. File/consult an issue if the migration name looks like a current, supported one

for _, m := range pending {
  if m.Name != "hooks" {
    fmt.Printf("migration %q has no automatic fix; run `bd doctor` for manual steps\n", m.Name)
  }
}

if err := fixPendingMigrations(pending, path); err != nil {
  if strings.Contains(err.Error(), "no automatic fix available") {
    // fall back to manual migration instructions from `bd doctor`
    return err
  }
}

When it happens

Trigger: `bd fix` encounters a pending migration whose Name is not 'hooks' — a newly introduced migration type before its fixer lands, or a stale/renamed migration recorded in the repository state.

Common situations: Running a newer bd that recorded a migration, then downgrading to a bd version lacking the fixer; or future migration types added to doctor detection ahead of fix support.

Related errors

• clone from %s succeeded, but the database needs %d schema %s
• building hook migration plan: %w
• hook migration is blocked: - %s
• applying hook migration: %w
• legacy SQLite release marker: %w

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