What causes "hydrate issue labels: %w" in gastownhall/beads?

Read the wrapped error to identify the underlying label-query failure.

hydrate issue labels: %w

Error message

hydrate issue labels: %w

What it means

After loading the stored issue, hydrateIssueOperation fetches its labels (from the wisp or issue plane as appropriate) and wraps failures with 'hydrate issue labels:'. The response payload includes labels, so a label-read failure aborts hydration. This keeps partial (label-less) issues from being silently returned to callers.

Source

Thrown at internal/storage/uow/issue_operations.go:170

	stored, useWisp, err := operationIssue(ctx, uw, issue.ID, issuePlaneOnly)
	if err != nil {
		return nil, fmt.Errorf("hydrate issue operation: %w", err)
	}
	clone := storageissueops.CloneCreateRequest(publicops.CreateRequest{Issue: stored}).Issue
	if !includeComments {
		clone.Comments = nil
	}
	labels := uw.LabelUseCase()
	if labels == nil {
		return nil, fmt.Errorf("hydrate issue labels: label use case is unavailable")
	}
	if useWisp {
		clone.Labels, err = labels.GetWispLabels(ctx, clone.ID)
	} else {
		clone.Labels, err = labels.GetLabels(ctx, clone.ID)
	}
	if err != nil {
		return nil, fmt.Errorf("hydrate issue labels: %w", err)
	}

	dependencies := uw.DependencyUseCase()
	if dependencies == nil {
		return nil, fmt.Errorf("hydrate issue dependencies: dependency use case is unavailable")
	}
	var records map[string][]*types.Dependency
	if useWisp {
		records, err = dependencies.GetWispDependencyRecords(ctx, []string{clone.ID})
	} else {
		records, err = dependencies.GetIssueDependencyRecords(ctx, []string{clone.ID})
	}
	if err != nil {
		return nil, fmt.Errorf("hydrate issue dependencies: %w", err)
	}
	clone.Dependencies = records[clone.ID]

	if includeComments {

View on GitHub (pinned to 71377f2769)

Solutions

Read the wrapped error to identify the underlying label-query failure.
Retry the operation; the UoW transaction model supports re-running the verb.
Verify the labels tables/schema are intact (e.g. after an upgrade run migrations/doctor).

Defensive patterns

Strategy: retry

Try / catch

if err != nil && strings.Contains(err.Error(), "hydrate issue labels") {
    return retryWithBackoff(op)
}

Prevention

Retry transient storage failures at the verb level.
Run schema checks after upgrades so label tables stay valid.
Alert on repeated label-read failures as a storage health signal.

When it happens

Trigger: GetLabels or GetWispLabels failing while hydrating a created/updated/closed issue — typically a query error or connectivity problem against the labels table.

Common situations: Database locked/unavailable mid-transaction; schema mismatch after a version upgrade; label use case misconfigured in the unit of work.

Related errors

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