gastownhall/beads · error

load custom statuses: %w

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).

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)

Solutions

1. Inspect the wrapped cause with errors.Is/errors.As to identify the underlying storage error
2. Verify the database is reachable and migrated (`bd doctor`); run pending migrations if any
3. Reconnect or reopen the store and retry
4. 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()}
}

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)
}

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

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
    }
}

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

• load custom types: %w
• get molecule children: %w
• database not available
• save notion.data_source_id: %w
• clear notion.view_url: %w

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