gastownhall/beads · error

failed to create user config.yaml: %w

Error message

failed to create user config.yaml: %w

What it means

When the user config.yaml does not yet exist, SetUserYamlConfig creates an empty file with os.WriteFile(path, []byte{}, 0o600) to establish the owner-private posture before writing keys. Failure of this initial creation is wrapped as 'failed to create user config.yaml'.

Source

Thrown at internal/config/yaml_config.go:499

	}

	return nil
}

func SetUserYamlConfig(key, value string) error {
	if err := validateYamlConfigValue(key, value); err != nil {
		return err
	}
	configPath, err := UserConfigYamlPath()
	if err != nil {
		return err
	}
	if err := os.MkdirAll(filepath.Dir(configPath), 0o755); err != nil {
		return fmt.Errorf("failed to create user config directory: %w", err)
	}
	if _, err := os.Stat(configPath); os.IsNotExist(err) {
		if err := os.WriteFile(configPath, []byte{}, 0o600); err != nil {
			return fmt.Errorf("failed to create user config.yaml: %w", err)
		}
	} else if err != nil {
		return fmt.Errorf("failed to stat user config.yaml: %w", err)
	}
	return setYamlConfigAtPath(configPath, key, value)
}

func setYamlConfigAtPath(configPath, key, value string) error {

	// Normalize key to canonical yaml format
	normalizedKey := normalizeYamlKey(key)

	// Read existing config
	content, err := os.ReadFile(configPath) //nolint:gosec // configPath is from findProjectConfigYaml
	if err != nil {
		return fmt.Errorf("failed to read config.yaml: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the parent directory (~/.beads) is writable: touch ~/.beads/.probe; fix with chown/chmod if not.
2. Free disk space / raise quota if ENOSPC.
3. Retry after closing programs locking the file (editors, AV, sync clients like Dropbox).
4. Pre-create the file yourself with correct mode: install -m 600 /dev/null ~/.beads/config.yaml, then rerun.

Example fix

// before
bd config set metrics.enabled true   // ENOSPC: failed to create user config.yaml
// after
df -h ~/.beads          # full -> clean space
bd config set metrics.enabled true

p := filepath.Join(home, ".beads", "config.yaml")
if _, err := os.Stat(p); os.IsNotExist(err) {
    if err := unix.Access(filepath.Dir(p), unix.W_OK); err != nil {
        return fmt.Errorf("cannot create config.yaml in %s: %w", filepath.Dir(p), err)
    }
}

err := config.SetUserYamlConfig(key, value)
if err != nil && strings.Contains(err.Error(), "failed to create user config.yaml") {
    _ = os.MkdirAll(filepath.Dir(userConfigPath), 0o755)
    f, cerr := os.OpenFile(userConfigPath, os.O_CREATE|os.O_WRONLY, 0o600)
    if cerr != nil { return cerr }
    f.Close()
    return config.SetUserYamlConfig(key, value)
}

When it happens

Trigger: First-time bd config set for a user with no config.yaml, where os.WriteFile fails: parent dir permissions changed between MkdirAll and write, read-only filesystem, quota/ENOSPC, or file lock on Windows.

Common situations: Fresh machine/CI container where HOME is not writable; antivirus holding a lock on the newly created file; disk quota exhausted on first write.

Related errors

• write metadata.json: %w
• failed to save config: %w
• failed to set beads.role config: %w
• failed to write config.yaml: %w
• failed to read config.yaml: %w

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