temporalio/temporal · error

task is not registered to a library

Error message

task is not registered to a library

What it means

RegistrableTask.fqType() builds the task's fully qualified name from its library's name plus the task type, needed to uniquely identify the task in the registry. It panics when rt.library is nil, i.e. the task was never registered to a library. Like the component variant, this guards an internal invariant: tasks are only expected to be reachable through their owning library.

Source

Thrown at chasm/registrable_task.go:195

}

// TaskGroup returns the side-effect task group for the task.
func (rt *RegistrableTask) TaskGroup() string {
	return rt.outboundTaskGroup
}

// GoType returns the reflect.Type of the task's Go struct.
func (rt *RegistrableTask) GoType() reflect.Type {
	return rt.goType
}

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

// WithTaskGroup sets the task group for the task. The task group is used when
// the side effect's destination is specified for grouping semantics on the outbound queue,
// affects multi-cursor and the circuit breaker.
// If task group isn't provided, the task group will default to the fully qualified name at library registration.
func WithTaskGroup(taskgroup string) RegistrableTaskOption {
	return func(rt *RegistrableTask) {
		rt.outboundTaskGroup = taskgroup
	}
}

// WithSingletonTask configures the task type as a singleton: at most one task of this type
// may exist per component instance at any time. The mode controls what happens when a new
// task is added while one already exists:
//   - [SingletonTaskModeReplace]: the existing task is removed and the new one takes its place.

View on GitHub (pinned to bde624efd1)

Solutions

  1. Register the task to a chasm library before use (via the library's task registration API)
  2. Don't construct RegistrableTask values directly; go through the library registration helpers
  3. Fix test setup so tasks are registered in a library fixture

Example fix

// before
task := &chasm.RegistrableTask{taskType: "SideEffect"}
task.FqType() // panics
// after
lib := chasm.NewLibrary(registry, "orders")
chasm.RegisterTask(lib, &OrderSideEffectTask{})
// FqType returns "orders/SideEffect"
Defensive patterns

Strategy: validation

Validate before calling

// register tasks via a library before use
lib := chasm.NewLibrary(registry, "mylib")
chasm.RegisterTask(lib, task) // sets library reference

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() (or otherwise triggering fqType) on a RegistrableTask created outside a library registration; also reachable from registerToLibrary flows if the task's library reference was never set before use.

Common situations: Directly constructing a RegistrableTask in tests or tooling; a refactor that detached task registration from library registration; using a task defined in a library whose registration failed earlier.

Related errors

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