gastownhall/beads · error

hierarchy.max-depth must be at least 1, got %d

Error message

hierarchy.max-depth must be at least 1, got %d

What it means

validateYamlConfigValue rejects a hierarchy.max-depth that parses as an integer but is less than 1 (GH#995 requires depth >= 1). The %d shows the parsed number. bd throws it because a zero or negative depth would make hierarchy traversal meaningless or infinite-loop-prone.

Source

Thrown at internal/config/yaml_config.go:886

	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)
		}
	case "prime.max-memories":
		n, err := strconv.Atoi(value)

View on GitHub (pinned to 71377f2769)

Solutions

1. Set at least 1: bd config set hierarchy.max-depth 1
2. To disable hierarchy traversal, comment out the key with UnsetYamlConfig instead of setting 0
3. Clamp computed/scripted values: if v < 1 { v = 1 } before calling SetYamlConfig
4. Review existing config.yaml for a bad stored value and correct it

Example fix

// before
SetYamlConfig("hierarchy.max-depth", "0") // error: must be at least 1
// after
SetYamlConfig("hierarchy.max-depth", "1") // or UnsetYamlConfig("hierarchy.max-depth")

n, err := strconv.Atoi(v)
if err != nil || n < 1 {
    return fmt.Errorf("hierarchy.max-depth must be >= 1, got %q", v)
}

func isValidMaxDepth(s string) bool {
    n, err := strconv.Atoi(s)
    return err == nil && n >= 1
}

if err := SetYamlConfig("hierarchy.max-depth", v); err != nil {
    if strings.Contains(err.Error(), "must be at least 1") {
        // clamp to 1 or unset the key instead
    }
    return err
}

When it happens

Trigger: SetYamlConfig-family calls with key "hierarchy.max-depth" and numeric values like "0", "-1", "-100".

Common situations: Trying to 'disable' hierarchy by setting 0 instead of unsetting; a script decrementing the value below 1; fat-fingering a negative number.

Related errors

• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• hierarchy.max-depth must be a positive integer, got %q
• 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/54dc449757f8de3b. Report an issue: GitHub.