remote name must start with a letter and contain only alphan

Error message

remote name must start with a letter and contain only alphanumeric characters, hyphens, and underscores

What it means

The final check enforces the full name grammar: it must start with a letter and contain only [A-Za-z0-9_-] (per validRemoteNameRegex). Anything with spaces, slashes, dots, or a non-letter first character fails here.

Source

Thrown at internal/remotecache/url.go:203

	}
	return nil
}

// ValidateRemoteName checks that a remote name is safe for use as a Dolt
// remote identifier. Names must start with a letter and contain only
// alphanumeric characters, hyphens, and underscores. Max 64 characters.
func ValidateRemoteName(name string) error {
	if name == "" {
		return fmt.Errorf("remote name cannot be empty")
	}
	if len(name) > 64 {
		return fmt.Errorf("remote name too long (max 64 characters)")
	}
	if strings.HasPrefix(name, "-") {
		return fmt.Errorf("remote name must not start with a dash")
	}
	if !validRemoteNameRegex.MatchString(name) {
		return fmt.Errorf("remote name must start with a letter and contain only alphanumeric characters, hyphens, and underscores")
	}
	return nil
}

// MatchesRemotePattern checks whether a URL matches a glob-style pattern.
// Patterns use path.Match semantics (e.g., "dolthub://myorg/*").
func MatchesRemotePattern(rawURL, pattern string) bool {
	matched, err := path.Match(pattern, rawURL)
	if err != nil {
		return false
	}
	return matched
}

// ValidateRemoteURLWithPatterns validates a URL and optionally checks it
// against an allowlist of glob patterns. If patterns is empty, only
// structural validation is performed.
func ValidateRemoteURLWithPatterns(rawURL string, patterns []string) error {

View on GitHub (pinned to 71377f2769)

Solutions

Rewrite the name to start with a letter and use only letters, digits, hyphens, underscores.
Sanitize the input: replace invalid characters with '-' and strip leading digits/dashes before calling.
Prefer short conventional aliases (origin, upstream, fork).

Example fix

// before
ValidateRemoteName("org/repo name")
// after
ValidateRemoteName("org-repo-name")

Defensive patterns

Strategy: validation

Validate before calling

var validRemoteName = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9_-]*$`)
if !validRemoteName.MatchString(name) {
    return fmt.Errorf("invalid remote name %q", name)
}

Try / catch

if err := remotecache.ValidateRemoteName(name); err != nil {
    return fmt.Errorf("remote name %q rejected: %w", name, err)
}

Prevention

Normalize user input: replace invalid characters with '-' and ensure a letter first.
Use constants like 'origin'/'upstream' instead of free-form names where possible.
Unit-test name sanitization with spaces, slashes, and leading digits.

When it happens

Trigger: Names like "1origin", "my remote", "org/repo", "foo.bar" passed to ValidateRemoteName or a remote-add flow.

Common situations: Users passing a URL, path, or issue key as the remote name; names with spaces from copy-paste; leading digits from generated identifiers.

Related errors

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