What causes "load custom statuses: %w" in gastownhall/beads?

Inspect the wrapped cause with errors.Is/errors.As to identify the underlying storage error

load custom statuses

Error message

load custom statuses: %w

What it means

This error is returned by LoadListConfig in internal/workapi/list.go when reading the workspace's custom statuses from the ConfigSource fails. LoadListConfig builds the ListConfig that BuildListFilter needs (custom statuses, custom types, infra types), and custom statuses are the first read; a failure here aborts the whole config load with the underlying cause wrapped. It is reached via LoadStoreListConfig (store handle) or LoadUOWListConfig (unit of work).

Solutions

Inspect the wrapped cause with errors.Is/errors.As to identify the underlying storage error
Verify the database is reachable and migrated (`bd doctor`); run pending migrations if any
Reconnect or reopen the store and retry
If the store cannot provide statuses, fall back to defaults or a nil store (LoadStoreListConfig already yields YAML custom types for a nil store)

Example fix

// before
cfg, err := workapi.LoadStoreListConfig(ctx, store)
if err != nil {
    return err // hard fail: 'load custom statuses: ...'
}
// after
cfg, err := workapi.LoadStoreListConfig(ctx, store)
if err != nil {
    log.Warnf("custom statuses unavailable, using defaults: %v", err)
    cfg = workapi.ListConfig{CustomTypes: config.GetCustomTypesFromYAML()}
}

Defensive patterns

Strategy: fallback

Validate before calling

if store == nil {
    // LoadStoreListConfig handles nil by using YAML custom types; do the same up front
cfg := workapi.ListConfig{CustomTypes: config.GetCustomTypesFromYAML()}
    return cfg, nil
}
if err := store.Ping(ctx); err != nil {
    return fmt.Errorf("store unreachable before list config load: %w", err)
}

Type guard

func isCustomStatusLoadError(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "load custom statuses: ")
}

Try / catch

cfg, err := workapi.LoadStoreListConfig(ctx, store)
if err != nil {
    if isCustomStatusLoadError(err) {
        log.Warnf("falling back to default statuses: %v", err)
        cfg = workapi.ListConfig{CustomTypes: config.GetCustomTypesFromYAML()}
    } else {
        return err
    }
}

Prevention

Run `bd doctor` (and pending migrations) after version upgrades before issuing list commands
Check store connectivity before loading list config in long-running frontends
Keep only one writer process on the workspace database to avoid lock contention
Remember a nil store is valid and yields YAML-based custom types; use it as a graceful degraded mode

When it happens

Trigger: Calling LoadStoreListConfig or LoadUOWListConfig (e.g. before `bd list`) where the store's GetCustomStatusesDetailed or the UOW's ConfigUseCase().GetCustomStatuses returns an error: the config/metadata table cannot be read (database unreachable, locked, corrupt, or the custom-statuses table missing after a failed migration).

Common situations: Running `bd list` with the Dolt server down or the database file locked; a version upgrade whose schema migration did not create the custom-statuses table; a corrupted workspace database; passing a store handle to a different/uninitialized workspace.

Related errors

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

Appendix: source

Thrown at internal/workapi/list.go:143

func (p uowConfigSource) GetCustomStatuses(ctx context.Context) ([]types.CustomStatus, error) {
	return p.uw.ConfigUseCase().GetCustomStatuses(ctx)
}
func (p uowConfigSource) GetCustomTypes(ctx context.Context) ([]string, error) {
	return p.uw.ConfigUseCase().GetCustomTypes(ctx)
}
func (p uowConfigSource) GetInfraTypes(ctx context.Context) (map[string]bool, error) {
	return p.uw.ConfigUseCase().GetInfraTypes(ctx)
}

// LoadListConfig materializes the list configuration from a ConfigSource,
// falling back to the workspace YAML for custom types the store does not know.
func LoadListConfig(ctx context.Context, src ConfigSource) (ListConfig, error) {
	var cfg ListConfig

	statuses, err := src.GetCustomStatuses(ctx)
	if err != nil {
		return cfg, fmt.Errorf("load custom statuses: %w", err)
	}
	cfg.CustomStatuses = statuses

	ct, err := src.GetCustomTypes(ctx)
	if err != nil {
		return cfg, fmt.Errorf("load custom types: %w", err)
	}
	if len(ct) > 0 {
		cfg.CustomTypes = ct
	} else {
		cfg.CustomTypes = config.GetCustomTypesFromYAML()
	}

	infraSet, err := src.GetInfraTypes(ctx)
	if err != nil {
		return cfg, fmt.Errorf("load infra types: %w", err)
	}
	if len(infraSet) > 0 {

View on GitHub (pinned to 71377f2769)