What causes "invalid --role %q: must be "maintainer" or "contributor"" in gastownhall/beads?

Use exactly --role=maintainer or --role=contributor (lowercase)

invalid --role %q: must be "maintainer" or "contributor"

Error message

invalid --role %q: must be "maintainer" or "contributor"

What it means

The --role flag only accepts the literal values "maintainer" or "contributor"; any other non-empty string is rejected with this error at init validation time.

Source

Thrown at cmd/bd/init.go:574

		}
		// Validate --database format early, before any side effects.
		if database != "" {
			if err := dolt.ValidateDatabaseName(database); err != nil {
				return fmt.Errorf("invalid database name %q: %v", database, err)
			}
		}

		// Resolve non-interactive mode: flag > env var > terminal detection.
		// This must be computed before any interactive prompts.
		nonInteractive := isNonInteractiveInit(nonInteractiveFlag)

		// Validate --role flag value
		if roleFlag != "" {
			switch roleFlag {
			case "maintainer", "contributor":
				// valid
			default:
				return fmt.Errorf("invalid --role %q: must be \"maintainer\" or \"contributor\"", roleFlag)
			}
		}

		// Fail-fast: contributor/team wizards require interaction
		if nonInteractive && contributor {
			return fmt.Errorf("--contributor requires interactive prompts and cannot be used with --non-interactive")
		}
		if nonInteractive && team {
			return fmt.Errorf("--team requires interactive prompts and cannot be used with --non-interactive")
		}

		// Dolt is the only supported backend.
		backend := configfile.BackendDolt

		// Also treat BEADS_DOLT_SERVER_MODE=1 env var as --server.
		if os.Getenv("BEADS_DOLT_SERVER_MODE") == "1" {
			initServerMode = true
		}

View on GitHub (pinned to 71377f2769)

Solutions

Use exactly --role=maintainer or --role=contributor (lowercase)
Drop --role to skip explicit role selection
Check the exact value for case and spelling

Example fix

// before
bd init --role=admin
// after
bd init --role=maintainer

Defensive patterns

Strategy: validation

Validate before calling

validRoles := map[string]bool{"maintainer": true, "contributor": true}
if roleFlag != "" && !validRoles[roleFlag] {
    return fmt.Errorf("--role must be maintainer or contributor")
}

Try / catch

if err := bdInit("--role=" + role); err != nil {
    if strings.Contains(err.Error(), "invalid --role") {
        // retry with "maintainer" or "contributor"
    }
}

Prevention

Only pass the exact lowercase literals maintainer/contributor
Whitelist role values in wrapper scripts
Omit --role when unsure

When it happens

Trigger: `bd init --role=<value>` where value is not exactly "maintainer" or "contributor" (e.g. --role=admin, --role=Maintainer, --role=dev).

Common situations: Guessing role names from other tools (admin/owner/dev), capitalization mismatches, pluralized values ("maintainers").

Related errors

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