apache/beam · error

invalid namespace, provide a different one

Error message

invalid namespace, provide a different one: %q contains the separator %q

What it means

validateNamespace rejects namespaces containing the Separator ':' because it would corrupt the scheme-qualified expansion address parsing. The error names the offending namespace and the separator character so the caller can pick another name.

Solutions

1. Strip the scheme and any colons; pass only the bare namespace token.
2. Use dashes or slashes-free identifiers instead of colons in generated namespace names.
3. Pre-validate with strings.Contains(ns, ":") in caller code for clearer user errors.

Example fix

// before
xlangx.RegisterHandler("acme:v1", h)
// after
xlangx.RegisterHandler("acme-v1", h)

if strings.Contains(namespace, ":") {
    return fmt.Errorf("namespace %q must not contain ':'", namespace)
}

if err := xlangx.RegisterHandler(ns, h); err != nil {
    return fmt.Errorf("invalid expansion namespace %q: %w", ns, err)
}

When it happens

Trigger: Registering a handler whose namespace string contains ":" — e.g. "http://x", "my:ns", or any URL-like value passed whole as the namespace.

Common situations: Passing a full expansion service URL as the namespace; concatenating scheme and name with a colon; copying an example URN ("namespace:urn") into the namespace parameter by mistake.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• invalide namespace, provide a different one
• xlangx.RegisterHandler
• capacity of cache cannot be negative, got
• could not unmarshal iterable coder from
• could not unmarshal nullable coder from

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/6aab01a583976ece. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/xlangx/registry.go:184

}

// RegisterHandler associates a namespace, with a handler.
//
// Namespaces may not have the configuration separator ":" in them,
// nor may they be a restricted namespace, like "localhost" or "http".
func (r *registry) RegisterHandler(namespace string, handler HandlerFunc) error {
	if err := validateNamespace(namespace); err != nil {
		return fmt.Errorf("xlangx.RegisterHandler: %v", err)
	}
	r.mu.Lock()
	defer r.mu.Unlock()
	r.handlers[namespace] = handler
	return nil
}

func validateNamespace(namespace string) error {
	if strings.Contains(namespace, Separator) {
		return fmt.Errorf("invalid namespace, provide a different one: %q contains the separator %q", namespace, Separator)
	}
	if _, ok := restricted[namespace]; ok {
		return fmt.Errorf("invalide namespace, provide a different one: %q is a restricted namespace", namespace)
	}
	return nil
}

// RegisterOverrideForUrn instructs using expansionAddr for CrossLanguage
// transforms with urn. expansionAddr should either be registered with an
// Expansion handler, or an Expansion service address.
func (r *registry) RegisterOverrideForUrn(urn, expansionAddr string) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if err := r.validateAddr(expansionAddr); err != nil {
		return fmt.Errorf("xlangx.RegisterExpansionForUrn(%q,%q) error: %v", urn, expansionAddr, err)
	}
	r.urnOverrides[urn] = expansionAddr
	return nil

View on GitHub (pinned to 12126d8942)