gastownhall/beads · error

hierarchy.max-depth must be a positive integer, got %q

Error message

hierarchy.max-depth must be a positive integer, got %q

What it means

validateYamlConfigValue rejects a hierarchy.max-depth value that is not parseable as an integer (GH#995). The %q shows the offending string exactly as provided. bd throws it to prevent storing a non-numeric depth that downstream hierarchy traversal would choke on.

Source

Thrown at internal/config/yaml_config.go:883

	if len(s) < 2 {
		return false
	}
	suffix := s[len(s)-1]
	if suffix != 's' && suffix != 'm' && suffix != 'h' {
		return false
	}
	return isNumeric(s[:len(s)-1])
}

// validateYamlConfigValue validates a configuration value before setting.
// Returns an error if the value is invalid for the given key.
func validateYamlConfigValue(key, value string) error {
	switch key {
	case "hierarchy.max-depth":
		// Must be a positive integer >= 1 (GH#995)
		depth, err := strconv.Atoi(value)
		if err != nil {
			return fmt.Errorf("hierarchy.max-depth must be a positive integer, got %q", value)
		}
		if depth < 1 {
			return fmt.Errorf("hierarchy.max-depth must be at least 1, got %d", depth)
		}
	case "dolt.shared-server":
		lower := strings.ToLower(value)
		if lower != "true" && lower != "false" {
			return fmt.Errorf("dolt.shared-server must be \"true\" or \"false\", got %q", value)
		}
	case "dolt.debug":
		lower := strings.ToLower(value)
		if lower != "true" && lower != "false" {
			return fmt.Errorf("dolt.debug must be \"true\" or \"false\", got %q", value)
		}
	case "dolt.mode":
		lower := strings.ToLower(value)
		if lower != "server" && lower != "embedded" {
			return fmt.Errorf("dolt.mode must be \"server\" or \"embedded\", got %q", value)

View on GitHub (pinned to 71377f2769)

Solutions

1. Set a plain positive integer, e.g. bd config set hierarchy.max-depth 5
2. Strip quotes, whitespace, units, and decimals from the value before setting
3. If scripted, validate with a shell/Go integer check before calling SetYamlConfig
4. Use UnsetYamlConfig to remove a bad existing value and re-set it correctly

Example fix

// before
SetYamlConfig("hierarchy.max-depth", "ten") // error
// after
SetYamlConfig("hierarchy.max-depth", "10")

v := "ten" // value to set
if _, err := strconv.Atoi(v); err != nil {
    return fmt.Errorf("hierarchy.max-depth must be an integer, got %q", v)
}

func isPositiveIntString(s string) bool {
    n, err := strconv.Atoi(s)
    return err == nil
}

if err := SetYamlConfig("hierarchy.max-depth", v); err != nil {
    if strings.Contains(err.Error(), "must be a positive integer") {
        // re-prompt or coerce to an integer, then retry
    }
    return err
}

When it happens

Trigger: SetYamlConfig / SetYamlConfigInDir / SetUserYamlConfig called with key "hierarchy.max-depth" and a value like "five", "", "3.5", "1e3", or " 3" (strconv.Atoi fails).

Common situations: Typing 'bd config set hierarchy.max-depth ten'; copy-pasting a float or quoted value; shell passing extra whitespace or units like '10 levels'.

Related errors

• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• hierarchy.max-depth must be at least 1, got %d
• dolt.shared-server must be "true" or "false", got %q

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