apache/beam · error

xlangx.RegisterHandler

Error message

xlangx.RegisterHandler: %v

What it means

registry.RegisterHandler associates an expansion-request namespace (URL scheme) with a HandlerFunc. Before registering, validateNamespace checks the name; any validation failure is wrapped as "xlangx.RegisterHandler: %v". This prevents namespaces that collide with the resolution syntax (e.g. containing ':') or reserved schemes.

Solutions

1. Remove ':' from the namespace string; register only the bare scheme/namespace.
2. Choose a non-reserved namespace distinct from "localhost", "http", etc.
3. Handle the returned error and surface a clear message to the configuring user.
4. Sanitize user-supplied namespace config before calling RegisterHandler.

Example fix

// before
err := xlangx.RegisterHandler("my-ns:v1", handler)
// after
err := xlangx.RegisterHandler("my-ns-v1", handler)

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

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

When it happens

Trigger: Calling xlangx.RegisterHandler with a namespace containing ":" (the Separator) or equal to a restricted namespace such as "localhost" or "http".

Common situations: Dynamically constructing namespaces from user config that includes a scheme like "http:"; typos using a colon-separated "namespace:urn" form as the namespace; attempting to override built-in schemes.

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
• invalide namespace, provide a different one
• xlangx.RegisterExpansionForUrn
• capacity of cache cannot be negative, got
• could not unmarshal iterable coder from

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

Appendix: source

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

	mu           sync.Mutex
	handlers     map[string]HandlerFunc // namespace -> handlerfuncs
	urnOverrides map[string]string      // URNs -> expansionAddrs
}

func newRegistry() *registry {
	return &registry{
		handlers:     map[string]HandlerFunc{},
		urnOverrides: map[string]string{},
	}
}

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

View on GitHub (pinned to 12126d8942)