What causes "hydrate ready row %s: dependency records: %w" in gastownhall/beads?

Unwrap the error chain to identify the underlying SQL/IO failure

hydrate ready row %s: dependency records: %w

Error message

hydrate ready row %s: dependency records: %w

What it means

HydrateReadyRowInTx failed to read dependency records for the claimed issue via GetDependencyRecordsForIssuesInTx. Like the counts read, a failure here is fatal to the claim: the whole transaction rolls back instead of returning a claimed issue with missing Dependencies.

Source

Thrown at internal/storage/issueops/claim_next.go:96

// state that transaction is about to commit.
//
// A failed count read is an error rather than a zero. The CLI's pre-role
// hydration swallowed all three, which meant a broken database reported a
// claimed issue with no dependencies rather than saying the read failed; here
// the whole claim rolls back instead, because a result nobody can hydrate is
// not a result.
func HydrateReadyRowInTx(ctx context.Context, tx *sql.Tx, issue *types.Issue) (*types.IssueWithCounts, error) {
	if issue == nil {
		return nil, nil
	}
	ids := []string{issue.ID}
	depCounts, err := GetDependencyCountsInTx(ctx, tx, ids)
	if err != nil {
		return nil, fmt.Errorf("hydrate ready row %s: dependency counts: %w", issue.ID, err)
	}
	records, err := GetDependencyRecordsForIssuesInTx(ctx, tx, ids)
	if err != nil {
		return nil, fmt.Errorf("hydrate ready row %s: dependency records: %w", issue.ID, err)
	}
	commentCounts, err := GetCommentCountsInTx(ctx, tx, ids)
	if err != nil {
		return nil, fmt.Errorf("hydrate ready row %s: comment counts: %w", issue.ID, err)
	}

	issue.Dependencies = records[issue.ID]
	counts := depCounts[issue.ID]
	if counts == nil {
		counts = &types.DependencyCounts{}
	}
	var parent *string
	for _, dep := range records[issue.ID] {
		if dep.Type == types.DepParentChild {
			parent = &dep.DependsOnID
			break
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

Unwrap the error chain to identify the underlying SQL/IO failure
Retry the claim — the transaction rolled back so state is unchanged
Repair or re-migrate the dependency tables if corruption is indicated

Example fix

if err != nil {
	var wrapped error
	if errors.As(err, &wrapped) {
		log.Printf("hydrate dependency records failed: %v", wrapped)
	}
	// claim fully rolled back; safe to retry
	result, err = store.ClaimNext(ctx, req)
}

Defensive patterns

Strategy: retry

Validate before calling

if err := store.Ping(ctx); err != nil {
	return fmt.Errorf("database unavailable before claim: %w", err)
}

Try / catch

result, err := store.ClaimNext(ctx, req)
if err != nil && strings.Contains(err.Error(), "dependency records") {
	// atomic rollback; retry in a fresh call
	result, err = store.ClaimNext(ctx, req)
}

Prevention

Verify dependency table integrity after migrations or imports
Retry transient failures — the claim is atomic and rollback-safe
Monitor the unwrapped cause (%w chain) for recurring IO/corruption signals

When it happens

Trigger: ExecuteClaimNext -> HydrateReadyRowInTx where GetDependencyRecordsForIssuesInTx errors — corrupt dependencies rows, connection failure, or schema problems in the dependency records query.

Common situations: Remote Dolt server connection dropped between claim and hydration; migration left dependency tables in an inconsistent state; disk I/O errors on an embedded database.

Related errors

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