temporalio/temporal · error

unknown archetypeID: %v

Error message

unknown archetypeID: %v

What it means

In the force-replication activity that translates a CHASM component archetypeID to its fully-qualified name, the chasmRegistry lookup ComponentFqnByID failed. The activity logs a structured error with the archetypeID and workflow context and returns this error, causing the Temporal activity to fail (and be retried per its retry policy).

Source

Thrown at service/worker/migration/activities.go:1312

		//  WorkflowArchetype here.
		return chasm.WorkflowArchetype, nil
	}

	// chasm activity and nexus operation libraries are not registered on worker service, so hardcoding
	// the mapping here for now.
	// TODO: Accept archetypeID in admin apis directly and remove this translation logic which relies on
	// chasm registry.
	if archetypeID == chasmactivity.ArchetypeID {
		return chasmactivity.Archetype, nil
	}
	if archetypeID == chasmnexus.ArchetypeID {
		return chasmnexus.Archetype, nil
	}

	archetype, ok := a.chasmRegistry.ComponentFqnByID(archetypeID)
	if !ok {
		activityInfo := activity.GetInfo(ctx)
		err := fmt.Errorf("unknown archetypeID: %v", archetypeID)
		a.Logger.Error("force-replication failed to translate archetypeID to name",
			tag.Error(err),
			tag.ArchetypeID(archetypeID),
			tag.WorkflowNamespace(activityInfo.WorkflowNamespace),
			tag.WorkflowID(activityInfo.WorkflowExecution.ID),
			tag.WorkflowRunID(activityInfo.WorkflowExecution.RunID),
		)
		return "", err
	}
	return archetype, nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Upgrade the worker/cluster binary so its CHASM registry includes the unknown archetypeID.
2. Verify the component was registered via its Register call; fix missing registration.
3. Check for version skew during rolling deploy — align deployments before running force-replication.
4. Inspect workflow history to identify which archetypeID is unknown and whether the payload is stale/corrupt.

Example fix

// before
archetype, ok := a.chasmRegistry.ComponentFqnByID(archetypeID)
if !ok {
    err := fmt.Errorf("unknown archetypeID: %v", archetypeID)
// after
archetype, ok := a.chasmRegistry.ComponentFqnByID(archetypeID)
if !ok {
    return nil, temporal.NewNonRetryableApplicationError(fmt.Sprintf("unknown archetypeID: %v", archetypeID), "UnknownArchetype")

// guard before calling the activity path that translates archetypeID
if _, ok := chasmRegistry.ComponentFqnByID(archetypeID); !ok {
    return fmt.Errorf("archetypeID %v not registered in this binary", archetypeID)
}

func archetypeKnown(reg chasm.Registry, archetypeID chasm.ArchetypeID) bool {
    _, ok := reg.ComponentFqnByID(archetypeID)
    return ok
}

When it happens

Trigger: An activity receives a request containing a CHASM archetypeID that is absent from the current chasm registry, e.g. a component type registered in a newer/older binary, so ComponentFqnByID returns ok=false.

Common situations: Version skew between clusters or services during a rolling upgrade where one side knows a newer CHASM component archetype and the worker's registry does not; stale workflow payloads referencing an archetype that was removed or renamed.

Related errors

• cannot handle replication task of type %v
• ErrDuplicateRegistration
• component type %s must be struct or pointer to struct
• component type %s is already registered
• task %s is already registered

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