apache/beam · error

invalide namespace, provide a different one

Error message

invalide namespace, provide a different one: %q is a restricted namespace

What it means

validateNamespace also rejects namespaces in the restricted set (e.g. "localhost", "http") so user handlers cannot hijack built-in resolution schemes. Note the message contains a typo ("invalide"). The error names the rejected namespace.

Solutions

1. Choose a custom namespace that is not a reserved scheme (prefix with your org/product name, e.g. "acme-expansion").
2. If you need to redirect expansions for specific transforms, use RegisterOverrideForUrn instead of RegisterHandler.
3. Filter reserved names in user-facing config before registration.

Example fix

// before
xlangx.RegisterHandler("localhost", h)
// after
xlangx.RegisterHandler("acme-local", h)

restricted := map[string]bool{"localhost": true, "http": true}
if restricted[namespace] {
    return fmt.Errorf("namespace %q is reserved; pick a custom one", namespace)
}

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

When it happens

Trigger: Calling xlangx.RegisterHandler with namespace exactly matching a key of the restricted map, such as "localhost" or "http".

Common situations: Trying to intercept expansion requests to localhost services by re-registering the localhost scheme; copying example addresses as namespaces; building generic handler registration that passes through user-supplied scheme names unfiltered.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid 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/0872d9ac0ef5cec1. Report an issue: GitHub.

Appendix: source

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

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

func (r *registry) validateAddr(expansionAddr string) error {

View on GitHub (pinned to 12126d8942)