gastownhall/beads · error

embeddeddolt: migrate: %w

Error message

embeddeddolt: migrate: %w

What it means

Returned by initSchema when schema.MigrateUp fails to apply pending schema migrations to the embedded database. Before this, initSchema has already done a forward-drift guard (database schema newer than the binary gets an explicit 'upgrade bd' message), so reaching this wrapper means MigrateUp itself errored on applying migrations — SQL failure mid-migration, context cancellation, dirty migration state with uncommitted working-set changes, or engine errors. The database may be left in a partially migrated state.

Source

Thrown at internal/storage/embeddeddolt/store.go:452

			// so both non-strict intents warn and continue on the current
			// schema instead of failing the open.
			switch s.intent {
			case openWorkingSetReconcile:
				fmt.Fprintf(os.Stderr,
					"Warning: %v\n"+
						"  Committing the working set at the current schema; when it completes,\n"+
						"  re-run 'bd migrate'.\n",
					dirtyErr)
			default: // openReadOnlyCommand
				fmt.Fprintf(os.Stderr,
					"Warning: %v\n"+
						"  Continuing without migrating. Run 'bd dolt commit' to commit the\n"+
						"  working set at the current schema, then re-run 'bd migrate'.\n",
					dirtyErr)
			}
			return nil
		}
		return fmt.Errorf("embeddeddolt: migrate: %w", err)
	}

	return nil
}

// GetIssue is implemented in get_issue.go.

func (s *EmbeddedDoltStore) GetIssueByExternalRef(ctx context.Context, externalRef string) (*types.Issue, error) {
	var id string
	err := s.withConn(ctx, false, func(tx *sql.Tx) error {
		var err error
		id, err = issueops.GetIssueByExternalRefInTx(ctx, tx, externalRef)
		return err
	})
	if err != nil {
		return nil, err
	}
	return s.GetIssue(ctx, id)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped inner error (%w) for the exact failing migration and SQL error.
2. Run 'bd doctor' to check and repair migration/schema state.
3. Commit or clean the Dolt working set ('bd dolt commit') then re-run 'bd migrate' as the error text above suggests.
4. Upgrade bd to the latest version so its migrations match the database schema era.
5. If partially migrated and unrecoverable, restore the data dir from git/Dolt remote or backup before retrying.

Example fix

// before
bd open  # embeddeddolt: migrate: dirty working set ... 

// after
bd dolt commit   # commit working set at current schema
bd migrate       # apply migrations explicitly, then open normally

if err := store.Init(ctx); err != nil && strings.Contains(err.Error(), "embeddeddolt: migrate") {
    // 1) commit working set at current schema
    exec.Command("bd", "dolt", "commit").Run()
    // 2) migrate explicitly, then retry init
    exec.Command("bd", "migrate").Run()
    err = store.Init(ctx)
    return err
}

When it happens

Trigger: newStore -> initSchema where MigrateUp returns an error other than the handled dirty-working-set case: (1) a migration statement fails (engine incompatibility, corrupt schema_version table); (2) context cancelled during a long migration; (3) dirty migration state where the working-set bailout path doesn't apply and the raw error is wrapped.

Common situations: Upgrading bd across many schema versions at once; interrupting a previous migration (kill/Ctrl-C) leaving partial state; running a newer database with an older binary in a way the drift guard missed (e.g. same-time edits); huge issue databases making migrations exceed the context deadline.

Related errors

• clone from %s succeeded, but the database needs %d schema %s
• legacy SQLite release marker: %w
• legacy SQLite schema drift in %s hidden column
• legacy SQLite schema drift in %s
• legacy SQLite issue %s uses unsupported removed fields

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