component %s has Field[*Visibility] but no businessID alias;

Error message

component %s has Field[*Visibility] but no businessID alias; use WithBusinessIDAlias option

What it means

validateVisibilityBusinessIDAlias enforces that any component whose struct contains a chasm Field[*Visibility] must declare a business ID alias via the WithBusinessIDAlias registration option. The Visibility field is used for search/visibility indexing, and without a business ID alias the framework cannot map visibility records back to business identifiers.

Source

Thrown at chasm/registry.go:350

}

func (r *Registry) validateName(n string) error {
	if n == "" {
		return errors.New("name must not be empty")
	}
	if !nameValidator.MatchString(n) {
		return fmt.Errorf("name %s is invalid. name must follow golang identifier rules: %s", n, nameValidator.String())
	}
	return nil
}

func (r *Registry) validateVisibilityBusinessIDAlias(rc *RegistrableComponent) error {
	if !hasVisibilityField(rc.goType) {
		return nil
	}
	// Archetypes that contain a Field[*Visibility] must specify WithBusinessIDAlias.
	if !rc.hasBusinessIDAlias() {
		return fmt.Errorf("component %s has Field[*Visibility] but no businessID alias; use WithBusinessIDAlias option", rc.componentType)
	}
	return nil
}

func (r *Registry) warnUnmanagedFields(fqn string, rc *RegistrableComponent) {
	var unmanagedFields []string
	for f := range unmanagedFieldsOf(rc.goType) {
		unmanagedFields = append(unmanagedFields, fmt.Sprintf("%s %s", f.name, f.typ))
	}
	if len(unmanagedFields) > 0 {
		r.logger.Info(fmt.Sprintf(
			"Warning: CHASM component %s declares state fields that won't be managed by CHASM:\n\t%s",
			fqn,
			strings.Join(unmanagedFields, "\n\t")))
	}
}

func (r *Registry) registerNexusService(svc *nexus.Service) error {

View on GitHub (pinned to bde624efd1)

Solutions

Add the WithBusinessIDAlias("<field-or-id>") option to the component's registration.
Pick the alias matching the business identifier the component should be searchable by.
Remove the Field[*Visibility] member if visibility/search is not needed for this component.

Example fix

// before
chasm.Register[OrderImpl](reg, chasm.WithComponentName("order"))
// after
chasm.Register[OrderImpl](reg, chasm.WithComponentName("order"), chasm.WithBusinessIDAlias("OrderID"))

Defensive patterns

Strategy: validation

Validate before calling

if hasVisibilityField(reflect.TypeOf(MyComponentImpl{})) && !hasBusinessIDAliasOption {
	return errors.New("component has Field[*Visibility]; add chasm.WithBusinessIDAlias")
}

Prevention

Whenever you add Field[*Visibility] to a component, add WithBusinessIDAlias in the same change.
Grep components for `Visibility` in code review and verify the registration options.
Cover component registration in a unit test that runs the registry validation.

When it happens

Trigger: Registering a component struct that has a `Field[*Visibility]` member but calling chasm.Register without the WithBusinessIDAlias option.

Common situations: Adding a Visibility field to a component for searchability and forgetting the new required option; copying a component definition that includes Visibility into a new component registered elsewhere; upgrading chasm where the alias requirement was introduced.

Related errors

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