temporalio/temporal · error

Unexpected frontend service name

Error message

Unexpected frontend service name

What it means

During fx (Uber Fx) dependency wiring in temporal/fx.go, the claim mapper provider selects a claim mapper implementation based on the running service name. Only FrontendService and InternalFrontendService are valid; any other service name reaching this provider means the app was assembled incorrectly, so fx panics at startup.

Source

Thrown at temporal/fx.go:604

	params ServiceProviderParamsCommon,
	serviceName primitives.ServiceName,
) (ServicesGroupOut, error) {
	if _, ok := params.ServiceNames[serviceName]; !ok {
		params.Logger.Info("Service is not requested, skipping initialization.", tag.Service(serviceName))
		return ServicesGroupOut{}, nil
	}

	app := fx.New(
		params.GetCommonServiceOptions(serviceName),
		fx.Supply(params.CustomFrontendInterceptors),
		fx.Decorate(func() authorization.ClaimMapper {
			switch serviceName {
			case primitives.FrontendService:
				return params.ClaimMapper
			case primitives.InternalFrontendService:
				return authorization.NewInternalClaimMapper()
			default:
				panic("Unexpected frontend service name")
			}
		}),
		fx.Decorate(func() log.SnTaggedLogger {
			// Use "frontend" for logs even if serviceName is "internal-frontend", but add an
			// extra tag to differentiate.
			tags := []tag.Tag{tag.Service(primitives.FrontendService)}
			if serviceName == primitives.InternalFrontendService {
				tags = append(tags, tag.Bool("internal-frontend", true))
			}
			return log.With(params.Logger, tags...)
		}),
		frontend.Module,
	)

	return NewService(app, serviceName, params.Logger), app.Err()
}

func WorkerServiceProvider(

View on GitHub (pinned to bde624efd1)

Solutions

1. Start the binary with the frontend service (or internal-frontend) — this provider only applies to those services
2. Use the correct fx options for history/matching/worker instead of frontend options
3. Check the --service flag / primitives.ServiceName passed at startup for typos

Example fix

// before: wrong service name in bootstrap
temporal-server start --service=fronend
// after
temporal-server start --service=frontend

switch serviceName {
case primitives.FrontendService, primitives.InternalFrontendService:
    // ok to build frontend fx app
default:
    return fmt.Errorf("claim mapper provider only supports frontend services, got %q", serviceName)
}

When it happens

Trigger: Raised in the fx.Provide factory for the claim mapper (temporal/fx.go:604) when serviceName is neither "frontend" nor "internal-frontend" — i.e. this provider was registered in an app for history/matching/worker, or the service name constant was mistyped in the binary's service bootstrap.

Common situations: Reusing the frontend fx app options to build another service; custom binaries wiring fx options from the wrong template; typos in --service flag values or renamed service primitives.

Related errors

• <dynamic archival cluster state err>
• Empty cluster information
• Master cluster name is empty
• missing current cluster metadata under clusterMetadata.Clust
• global.authorization.remoteClusterAuth.require is true but n

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