What causes "list dep metadata: %w" in gastownhall/beads?

Inspect the wrapped cause for connectivity vs schema errors

list dep metadata: %w

Error message

list dep metadata: %w

What it means

Wraps a repository failure from depRepo.ListWithIssueMetadata after the sourceID validation passed. The metadata-augmented dependency listing against the storage layer failed; the cause is preserved.

Source

Thrown at internal/storage/domain/dependency.go:527

func (u *dependencyUseCaseImpl) IterWispWithIssueMetadata(ctx context.Context, wispID string, filter DepListFilter) (storage.Iter[types.IssueWithDependencyMetadata], error) {
	return u.iterWithMetadata(ctx, wispID, filter, true)
}

func (u *dependencyUseCaseImpl) CountByWispID(ctx context.Context, wispID string, filter DepListFilter) (int64, error) {
	return u.countByID(ctx, wispID, filter, true)
}

func (u *dependencyUseCaseImpl) listWithMetadata(ctx context.Context, sourceID string, filter DepListFilter, useWisp bool) ([]*types.IssueWithDependencyMetadata, error) {
	if sourceID == "" {
		return nil, fmt.Errorf("list dep metadata: sourceID must not be empty")
	}
	out, err := u.depRepo.ListWithIssueMetadata(ctx, sourceID, DepListOpts{
		Types:         filter.Types,
		Direction:     filter.Direction,
		UseWispsTable: useWisp,
	})
	if err != nil {
		return nil, fmt.Errorf("list dep metadata: %w", err)
	}
	return out, nil
}

func (u *dependencyUseCaseImpl) iterWithMetadata(ctx context.Context, sourceID string, filter DepListFilter, useWisp bool) (storage.Iter[types.IssueWithDependencyMetadata], error) {
	if sourceID == "" {
		return nil, fmt.Errorf("iter dep metadata: sourceID must not be empty")
	}
	it, err := u.depRepo.IterWithIssueMetadata(ctx, sourceID, DepListOpts{
		Types:         filter.Types,
		Direction:     filter.Direction,
		UseWispsTable: useWisp,
	})
	if err != nil {
		return nil, fmt.Errorf("iter dep metadata: %w", err)
	}
	return it, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause for connectivity vs schema errors
Verify migrations are current for the metadata join query
Retry with a valid context deadline
If using wisps variant, confirm the wisps table exists or fall back to the main listing

Defensive patterns

Strategy: try-catch

Validate before calling

if sourceID == "" {
	return fmt.Errorf("sourceID required")
}

Try / catch

out, err := u.ListWithIssueMetadata(ctx, sourceID, filter)
if err != nil {
	var root error
	errors.As(err, &root)
	// root may be dberrors.TableNotExist for the wisp variant
}

Prevention

Guard empty IDs before calling
Run migrations before schema-dependent joins
Use ListWispWithIssueMetadata only when wisps are enabled
Apply deadlines appropriate for large dependency graphs

When it happens

Trigger: Calling ListWithIssueMetadata or ListWispWithIssueMetadata with a valid non-empty sourceID where ListWithIssueMetadata on depRepo returns an error (for any UseWispsTable setting).

Common situations: DB unavailable or query timeout; source issue exists but the joined metadata query hits a schema mismatch after an upgrade; large dependency graphs exceeding query limits.

Related errors

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