gastownhall/beads · error · storage.ErrNotInitialized

%w: issue_prefix config is missing (run 'bd init --prefix <p

Error message

%w: issue_prefix config is missing (run 'bd init --prefix <prefix>' for a new project, or 'bd bootstrap' to clone an existing remote; if using config.yaml, use key 'issue-prefix', not 'issue_prefix')

What it means

The project is not initialized: there is no issue_prefix value in the database config table (or it is empty), so issue IDs cannot be generated. The error wraps storage.ErrNotInitialized and explains the exact remediation, including the common config.yaml key mistake ('issue_prefix' instead of 'issue-prefix').

Source

Thrown at internal/storage/issueops/helpers.go:527

func IsDoltNothingToCommit(err error) bool {
	if err == nil {
		return false
	}
	s := strings.ToLower(err.Error())
	return strings.Contains(s, "nothing to commit") ||
		(strings.Contains(s, "no changes") && strings.Contains(s, "commit"))
}

// ReadConfigPrefix reads and normalizes issue_prefix from the config table.
func ReadConfigPrefix(ctx context.Context, tx DBTX) (string, error) {
	var configPrefix string
	err := tx.QueryRowContext(ctx, "SELECT value FROM config WHERE `key` = ?", "issue_prefix").Scan(&configPrefix)
	if err == sql.ErrNoRows || configPrefix == "" {
		yamlPrefix := strings.TrimSpace(config.GetString("issue-prefix"))
		underscoreYamlPrefix := strings.TrimSpace(config.GetString("issue_prefix"))
		debug.Logf("Debug: missing config.issue_prefix in database (err=%v, db value=%q, yaml issue-prefix=%q, yaml issue_prefix=%q)\n",
			err, configPrefix, yamlPrefix, underscoreYamlPrefix)
		return "", fmt.Errorf("%w: issue_prefix config is missing (run 'bd init --prefix <prefix>' for a new project, or 'bd bootstrap' to clone an existing remote; if using config.yaml, use key 'issue-prefix', not 'issue_prefix')", storage.ErrNotInitialized)
	} else if err != nil {
		return "", fmt.Errorf("failed to get config: %w", err)
	}
	return strings.TrimSuffix(configPrefix, "-"), nil
}

// ---------------------------------------------------------------------------
// Nullable value helpers
// ---------------------------------------------------------------------------

// NullString returns nil for empty strings, otherwise the string value.
func NullString(s string) interface{} {
	if s == "" {
		return nil
	}
	return s
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run 'bd init --prefix <prefix>' in the repository to write issue_prefix into the database config.
2. If cloning an existing project's remote, run 'bd bootstrap' to pull config and data.
3. If configuring via config.yaml, rename the key to 'issue-prefix' (hyphen, not underscore): `issue-prefix: PROJ`.
4. Verify with `bd config get issue_prefix` (or inspect the config table) that a non-empty value is present before retrying.

Example fix

// before: config.yaml
issue_prefix: PROJ   # wrong key, ignored
// after
issue-prefix: PROJ
// or, preferred: initialize the database config
// $ bd init --prefix PROJ

func ensureInitialized(repoDir string) error {
    if _, err := os.Stat(filepath.Join(repoDir, ".beads")); err != nil {
        return fmt.Errorf("run 'bd init --prefix <prefix>' or 'bd bootstrap' first")
    }
    // config.yaml check: correct key is issue-prefix (hyphen)
    if data, err := os.ReadFile(filepath.Join(repoDir, "config.yaml")); err == nil {
        if bytes.Contains(data, []byte("issue_prefix:")) {
            return fmt.Errorf("config.yaml uses 'issue_prefix:'; rename to 'issue-prefix:'")
        }
    }
    return nil
}

prefix, err := storage.ReadConfigPrefix(ctx, tx)
if errors.Is(err, storage.ErrNotInitialized) {
    // initialize then retry
    if e := runBdInit(repoDir, defaultPrefix); e != nil { return e }
    prefix, err = storage.ReadConfigPrefix(ctx, tx)
}

When it happens

Trigger: Running any command that needs an issue ID (bd create, etc.) via NewBatchContext/ReadConfigPrefix against a database where the config table lacks an issue_prefix row — fresh/uninitialized DB, config.yaml missing or using the wrong key, or a cloned repo without 'bd bootstrap'.

Common situations: Cloning a repo and skipping 'bd bootstrap'; writing `issue_prefix: PROJ` in config.yaml instead of `issue-prefix: PROJ`; running bd in a directory with no .beads database; a fresh checkout before 'bd init'.

Related errors

• dolt directory is required
• invalid database name: %q; hyphens are not allowed in embedd
• embeddeddolt: invalid database name: %q; hyphens are not all
• %w. Hint: run 'bd init' to create a database in the current
• failed to open database: %w Hint: %s

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