gastownhall/beads · error

peer name too long (max 64 characters)

Error message

peer name too long (max 64 characters)

What it means

validatePeerName caps peer names at 64 characters because the name is used as a Dolt remote name and must remain safe/short. Names longer than 64 characters are rejected with this error before any credential or remote setup happens.

Source

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

// 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
	}

	keyPath := filepath.Join(s.beadsDir, credentialKeyFile)

View on GitHub (pinned to 71377f2769)

Solutions

1. Shorten the peer name to 64 characters or fewer, e.g. `bd peer add backup` instead of the full URL
2. Derive a short canonical name from the long identifier (org-repo abbreviation) in your scripts
3. Store the long endpoint in the peer's URL/config field and keep the name short

Example fix

// before
bd peer add https://doltremoteapi.dolthub.com/gastownhall/beads   # too long
// after
bd peer add dolthub-beads --url https://doltremoteapi.dolthub.com/gastownhall/beads

func validPeerNameLength(name string) bool { return len(name) > 0 && len(name) <= 64 }

When it happens

Trigger: addFederationPeer receives a peer name whose len(name) > 64 — e.g. a full URL, a UUID with prefixes, or a generated identifier pasted directly as the peer name.

Common situations: Pasting a remote URL or long hostname as the peer name; programmatically generating names from long org/repo paths; concatenating environment prefixes that blow past 64 chars.

Related errors

• peer name must start with a letter and contain only alphanum
• peer name cannot be empty
• peer name must start with a letter and contain only alphanum
• invalid peer name: %w
• peer name cannot be empty

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