gastownhall/beads · error

peer name cannot be empty

Error message

peer name cannot be empty

What it means

validatePeerName rejects an empty peer name when adding a federation peer credential. Peer names become Dolt remote names, so they must be non-empty, start with a letter, and contain only alphanumerics, hyphens, and underscores (max 64 chars). This is the empty-name branch.

Source

Thrown at internal/storage/dolt/credentials.go:42

// Credential storage and encryption for federation peers.
// Enables SQL user authentication when syncing with peer workspaces.

// credentialKeyFile is the filename for the random encryption key stored alongside the database.
const credentialKeyFile = ".beads-credential-key" //nolint:gosec // G101: not a credential, just a filename

const awsResponseChecksumValidationEnv = "AWS_RESPONSE_CHECKSUM_VALIDATION"

// federationEnvMutex protects process-wide env vars from concurrent access.
// Environment variables are process-global, so we need to serialize federation operations.
var federationEnvMutex sync.Mutex

// validPeerNameRegex matches valid peer names (alphanumeric, hyphens, underscores)
var validPeerNameRegex = regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`)

// validatePeerName checks that a peer name is safe for use as a Dolt remote name
func validatePeerName(name string) error {
	if name == "" {
		return fmt.Errorf("peer name cannot be empty")
	}
	if len(name) > 64 {
		return fmt.Errorf("peer name too long (max 64 characters)")
	}
	if !validPeerNameRegex.MatchString(name) {
		return fmt.Errorf("peer name must start with a letter and contain only alphanumeric characters, hyphens, and underscores")
	}
	return nil
}

// initCredentialKey loads or generates the credential encryption key.
// The key file is stored in .beads/ (beadsDir), NOT in .beads/dolt/ (dbPath),
// to avoid creating ghost directories in shared-server mode (GH bd-cby).
// Falls back to the old dbPath location for transparent migration.
func (s *DoltStore) initCredentialKey(ctx context.Context) error {
	if s.beadsDir == "" {
		return nil // No filesystem path — credential encryption unavailable
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Supply a non-empty peer name, e.g. `bd peer add alice` / set `name: "alice"` in config
2. Check the shell variable or config key actually has a value before invoking (`echo "$PEER"`)
3. Use a name starting with a letter, e.g. `peer-1` or `backup_remote`

Example fix

// before
PEER=""; bd peer add "$PEER"   # peer name cannot be empty
// after
PEER="backup-remote"; bd peer add "$PEER"

// same rules as validatePeerName
var peerNameRe = regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`)
func validPeerName(name string) bool {
    return name != "" && len(name) <= 64 && peerNameRe.MatchString(name)
}

func validPeerName(name string) bool {
    return name != "" && len(name) <= 64 &&
        regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`).MatchString(name)
}

When it happens

Trigger: addFederationPeer is called (or a `bd` federation/peer add command run) with an empty string as the peer name — e.g. a missing CLI argument, an unset config field, or an empty env var interpolated into the peer name.

Common situations: Forgot to pass the peer name argument on the CLI; YAML/JSON config with `name: ""`; scripting with an unset variable (`bd peer add $PEER` with PEER empty).

Related errors

• peer name too long (max 64 characters)
• peer name must start with a letter and contain only alphanum
• peer name cannot be empty
• peer name too long (max 64 characters)
• peer name must start with a letter and contain only alphanum

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