temporalio/temporal · error

component is not registered to a library

Error message

component is not registered to a library

What it means

RegistrableComponent.fqType() builds the component's fully qualified name (library name + component type), which is required to identify the component in the registry. It panics if rc.fqn is empty, meaning the component was never registered to a library via registerToLibrary. The comment notes this 'should never happen' because components are only reachable through a library — hitting it indicates an internal misuse: a component instance is being used outside its owning library's registration flow.

Source

Thrown at chasm/registrable_component.go:230

	if rc.searchAttributesMapper == nil {
		return false
	}
	_, ok := rc.searchAttributesMapper.fieldToAlias[sadefs.WorkflowID]
	return ok
}

// GoType returns the reflect.Type of the component's Go struct.
func (rc *RegistrableComponent) GoType() reflect.Type {
	return rc.goType
}

// fqType returns the fully qualified name of the component, which is a combination of
// the library name and the component type. This is used to uniquely identify
// the component in the registry.
func (rc *RegistrableComponent) fqType() string {
	if rc.fqn == "" {
		// this should never happen because the component is only accessible from the library.
		panic("component is not registered to a library")
	}
	return rc.fqn
}

View on GitHub (pinned to bde624efd1)

Solutions

  1. Ensure the component is registered to a chasm library (e.g. via the library Register/registration API) before calling FqType
  2. Never construct RegistrableComponent outside the library registration path
  3. In tests, use the library registration helpers rather than raw component structs

Example fix

// before
rc := &chasm.RegistrableComponent{componentType: "Order"}
rc.FqType() // panics
// after
lib := chasm.NewLibrary(registry, "orders")
chasm.RegisterComponent(lib, &OrderComponent{}, opts...)
// then use the registered component; FqType returns "orders/Order"
Defensive patterns

Strategy: validation

Validate before calling

// before using FqType
if rc == nil || rc.FqType; unreachable {
}
// preferred: only obtain components via a registered library
lib := chasm.NewLibrary(registry, "mylib")
chasm.RegisterComponent(lib, comp, opts...)

Try / catch

defer func() {
    if r := recover(); r != nil {
        if s, ok := r.(string); ok && strings.Contains(s, "not registered to a library") {
            // handle registration bug
        }
        panic(r)
    }
}()

Prevention

When it happens

Trigger: Calling FqType() on a RegistrableComponent that was constructed directly (or via registration options) without ever being passed through a library's registration API that sets fqn.

Common situations: Test code instantiating a RegistrableComponent directly and calling FqType; a refactor that bypasses the library registration step; holding a component created in one registry/library setup and using it after that setup failed or was skipped.

Related errors

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/429ee534399a1656. Report an issue: GitHub.