gastownhall/beads · error

failed to save config: %w

Error message

failed to save config: %w

What it means

ConfigValues wraps errors from cfg.Save(beadsDir) with this message. Save rewrites .beads/metadata.json after fixing the database field (e.g. "beads.db" → "dolt" for the Dolt backend); it fails when the file cannot be written — permissions, read-only filesystem, or disk errors.

Source

Thrown at cmd/bd/doctor/fix/config_values.go:43

	fixed := false

	// Fix database field: when backend is Dolt, database should be "dolt" not "beads.db"
	if cfg.GetBackend() == configfile.BackendDolt {
		if strings.HasSuffix(cfg.Database, ".db") || strings.HasSuffix(cfg.Database, ".sqlite") || strings.HasSuffix(cfg.Database, ".sqlite3") {
			fmt.Printf("  Updating database: %q → %q (Dolt backend uses directory)\n", cfg.Database, "dolt")
			cfg.Database = "dolt"
			fixed = true
		}
	}

	if !fixed {
		fmt.Println("  → No configuration issues to fix")
		return nil
	}

	if err := cfg.Save(beadsDir); err != nil {
		return fmt.Errorf("failed to save config: %w", err)
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Ensure the current user has write permission on .beads/metadata.json (ls -l .beads/metadata.json; chown/chmod as needed)
2. Do not mix sudo and non-sudo bd runs; fix ownership: sudo chown -R $USER .beads
3. Check the filesystem is not mounted read-only (mount | grep <path>) and remount read-write
4. Free disk space or close programs locking the file, then rerun the fix

Example fix

// shell
$ bd doctor fix   # failed to save config: permission denied
$ sudo chown -R $USER .beads && bd doctor fix

fi, err := os.Stat(filepath.Join(beadsDir, "metadata.json"))
if err != nil { return err }
if fi.Mode().Perm()&0o200 == 0 { return fmt.Errorf("metadata.json is not writable") }
if err := syscall.Access(filepath.Join(beadsDir, "metadata.json"), syscall.O_RDWR); err != nil {
    return fmt.Errorf("no write access: %w", err)
}

func metadataWritable(beadsDir string) bool {
    return unix.Access(filepath.Join(beadsDir, "metadata.json"), unix.W_OK) == nil
}

if err := fix.ConfigValues(path); err != nil {
    if strings.HasPrefix(err.Error(), "failed to save config") {
        // check permissions/read-only mount, fix, then retry
    }
    return err
}

When it happens

Trigger: cfg.Save fails after ConfigValues detected and applied a fix: metadata.json is read-only, owned by another user, the filesystem is mounted read-only, or the disk is full.

Common situations: Running `bd doctor fix` under sudo (or without it) so file ownership mismatches afterwards; workspace on a read-only mount or in a container with a read-only layer; antivirus/backup tools holding the file open on Windows.

Related errors

• dolt path is not executable
• failed to create backup directory: %w
• failed to create temp file: %w
• write metadata.json: %w
• failed to create backup file: %w

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