{"record":{"id":"53ba1d6768c28695","repo":"temporalio/temporal","slug":"error-loading-nexus-endpoints-cache-w","errorCode":null,"errorMessage":"error loading nexus endpoints cache: %w","messagePattern":"error loading nexus endpoints cache: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/matching/nexus_endpoint_client.go","lineNumber":92,"sourceCode":"\tendpointsRefreshInterval dynamicconfig.DurationPropertyFn,\n\tpersistence p.NexusEndpointManager,\n) *nexusEndpointClient {\n\treturn &nexusEndpointClient{\n\t\tendpointsRefreshInterval: endpointsRefreshInterval,\n\t\tpersistence:              persistence,\n\t\ttableVersionChanged:      make(chan struct{}),\n\t}\n}\n\nfunc (m *nexusEndpointClient) CreateNexusEndpoint(\n\tctx context.Context,\n\trequest *internalCreateNexusEndpointRequest,\n) (*matchingservice.CreateNexusEndpointResponse, error) {\n\tif !m.hasLoadedEndpoints.Load() {\n\t\t// Endpoints must be loaded into memory before Create so we know whether this endpoint name is in use and that we\n\t\t// have the last known table version to update persistence.\n\t\tif err := m.loadEndpoints(ctx); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error loading nexus endpoints cache: %w\", err)\n\t\t}\n\t}\n\n\tm.Lock()\n\tdefer m.Unlock()\n\n\tif _, exists := m.endpointsByName[request.spec.GetName()]; exists {\n\t\treturn nil, serviceerror.NewAlreadyExistsf(\"error creating Nexus endpoint. Endpoint with name %v already registered\", request.spec.GetName())\n\t}\n\n\tentry := &persistencespb.NexusEndpointEntry{\n\t\tVersion: 0,\n\t\tId:      uuid.NewString(),\n\t\tEndpoint: &persistencespb.NexusEndpoint{\n\t\t\tClock:       hlc.Zero(request.clusterID),\n\t\t\tSpec:        request.spec,\n\t\t\tCreatedTime: timestamppb.New(request.timeSource.Now().UTC()),\n\t\t},","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/service/matching/nexus_endpoint_client.go#L74-L110","documentation":"CreateNexusEndpoint must load the entire Nexus endpoints table into the matching engine's in-memory cache before creating a new endpoint, both to enforce name-uniqueness and to know the last table version for a conditional persistence update. This error wraps any failure of that initial loadEndpoints call (persistence read, version conflicts, context cancellation).","triggerScenarios":"Calling the matching service CreateNexusEndpoint API when hasLoadedEndpoints is false and loadEndpoints fails — typically a persistence/DB error reading the nexus endpoints table or a cancelled/deadlined context.","commonSituations":"Database outage or degradation on the first endpoint operation after matching service start; context deadline exceeded while loading a large endpoints table; ops tooling (tctl nexus endpoint create) hitting an unhealthy DB.","solutions":["Retry the CreateNexusEndpoint call once the database/persistence layer is reachable — the cache load is retried on the next call","Inspect the wrapped cause (%w) for persistence errors and fix the underlying DB issue (connectivity, permissions, timeouts)","Increase the client request timeout if loadEndpoints times out on large tables","Check matching service logs for repeated loadEndpoints failures indicating schema or shard issues"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp, err := client.MatchingClient().CreateNexusEndpoint(ctx, req)\nif err != nil {\n\tvar persistenceErr *persistence.OperationFailedError // inspect cause via errors.Unwrap\n\tif errors.Is(err, context.DeadlineExceeded) || isTransientDBError(err) {\n\t\t// retry after backoff\n\t}\n\treturn fmt.Errorf(\"create nexus endpoint failed: %w\", err)\n}","preventionTips":["Ensure the visibility/persistence DB is healthy before running nexus endpoint admin operations","Set generous client timeouts — the first call after startup pays the full table-load cost","Retry idempotently: create failures during cache load are safe to retry","Check for name collisions before creating to avoid unrelated create failures"],"tags":["go","nexus","matching-service","persistence","cache"],"backgroundTag":"nexus-endpoint-cache-load-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}