gastownhall/beads · error

ensure user config: %w

Error message

ensure user config: %w

What it means

EnsureUserConfigDefaults ensures the user's bd config YAML exists and contains the metrics defaults block. If the config path itself cannot be determined (config.UserConfigYamlPath fails), it wraps the cause as 'ensure user config: ...'. It cannot proceed to read or bootstrap the file without a resolved path.

Source

Thrown at internal/metrics/userconfig.go:22

	"errors"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"regexp"
	"strings"

	"gopkg.in/yaml.v3"

	"github.com/steveyegge/beads/internal/config"
)

var commentedMetricsRe = regexp.MustCompile(`(?m)^\s*#\s*metrics\s*:`)

func EnsureUserConfigDefaults() error {
	path, err := config.UserConfigYamlPath()
	if err != nil {
		return fmt.Errorf("ensure user config: %w", err)
	}

	data, err := os.ReadFile(path) //nolint:gosec // path is a validated absolute user config path
	if errors.Is(err, fs.ErrNotExist) {
		return writeUserConfigBootstrap(path)
	}
	if err != nil {
		return fmt.Errorf("ensure user config: read %s: %w", path, err)
	}

	if commentedMetricsRe.Match(data) {
		return nil
	}

	var root yaml.Node
	if err := yaml.Unmarshal(data, &root); err != nil {
		return fmt.Errorf("ensure user config: parse %s: %w", path, err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Set HOME (and optionally XDG_CONFIG_HOME) to a writable location before running bd.
2. Ensure the resolved config directory exists and is writable.
3. Inspect the wrapped cause (%w) for the exact path-resolution error.

Example fix

// before
err := metrics.EnsureUserConfigDefaults() // fails when HOME unset
// after
if os.Getenv("HOME") == "" {
    os.Setenv("HOME", "/home/agent")
}
err := metrics.EnsureUserConfigDefaults()

if os.Getenv("HOME") == "" && os.Getenv("XDG_CONFIG_HOME") == "" {
    return fmt.Errorf("cannot locate user config: HOME/XDG_CONFIG_HOME unset")
}

if err := metrics.EnsureUserConfigDefaults(); err != nil {
    if strings.HasPrefix(err.Error(), "ensure user config") {
        return nil // skip defaults; config path unavailable
    }
    return err
}

When it happens

Trigger: Calling EnsureUserConfigDefaults when config.UserConfigYamlPath returns an error — typically HOME unset or an XDG config path resolution failure. Callers include writeUserConfigBootstrap and the EnsureUserConfigDefaults test suite.

Common situations: Running bd in a container/CI with HOME unset; malformed XDG_CONFIG_HOME pointing somewhere unusable; environment where user config conventions cannot be satisfied.

Related errors

• metrics: resolve data dir: %w
• multiple .doltcfg directories detected
• no .beads directory found
• resolving beads dir %s: %w
• resolving physical root %s: %w

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