{"record":{"id":"bbda73421d145edc","repo":"temporalio/temporal","slug":"error-loading-nexus-endpoint-cache-w","errorCode":null,"errorMessage":"error loading nexus endpoint cache: %w","messagePattern":"error loading nexus endpoint cache: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/matching/nexus_endpoint_client.go","lineNumber":143,"sourceCode":"\tm.insertEndpointLocked(entry)\n\tch := m.tableVersionChanged\n\tm.tableVersionChanged = make(chan struct{})\n\tclose(ch)\n\n\treturn &matchingservice.CreateNexusEndpointResponse{\n\t\tEntry: entry,\n\t}, nil\n}\n\nfunc (m *nexusEndpointClient) UpdateNexusEndpoint(\n\tctx context.Context,\n\trequest *internalUpdateNexusEndpointRequest,\n) (*matchingservice.UpdateNexusEndpointResponse, error) {\n\tif !m.hasLoadedEndpoints.Load() {\n\t\t// Endpoints must be loaded into memory before Update, since we need to check the previous entry and we need the\n\t\t// 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 endpoint cache: %w\", err)\n\t\t}\n\t}\n\n\tm.Lock()\n\tdefer m.Unlock()\n\n\tprevious, exists := m.endpointsByID[request.endpointID]\n\tif !exists {\n\t\treturn nil, serviceerror.NewNotFoundf(\"error updating Nexus endpoint. endpoint ID %v not found\", request.endpointID)\n\t}\n\n\tif request.version != previous.Version {\n\t\treturn nil, serviceerror.NewFailedPreconditionf(\"nexus endpoint version mismatch. received: %v expected %v\", request.version, previous.Version)\n\t}\n\n\tentry := &persistencespb.NexusEndpointEntry{\n\t\tVersion: previous.Version,\n\t\tId:      previous.Id,","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/service/matching/nexus_endpoint_client.go#L125-L161","documentation":"UpdateNexusEndpoint requires the in-memory Nexus endpoints cache to be loaded before updating, because it must check the previous entry and carry the last known table version into the conditional persistence update. This error wraps failure of the loadEndpoints call made lazily on the first Update request after service start.","triggerScenarios":"Calling matching service UpdateNexusEndpoint when hasLoadedEndpoints is false (first use since startup or after a version regression that reset the flag) and loadEndpoints returns an error from persistence or context cancellation.","commonSituations":"Updating an endpoint via tctl/admin right after matching service restart during a DB outage; context deadline exceeded while loading endpoints; persistence errors (connection refused, shard unavailable).","solutions":["Retry the UpdateNexusEndpoint call after the persistence layer recovers","Check and fix the underlying cause in the wrapped error (DB connectivity, timeouts)","Increase request timeouts if endpoint-table loading is slow","Verify the matching service can read the nexus endpoints table (schema/permissions)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp, err := client.MatchingClient().UpdateNexusEndpoint(ctx, req)\nif err != nil && isTransient(err) {\n\t// backoff and retry; cache load will be re-attempted\n}","preventionTips":["Verify DB connectivity before admin endpoint updates","Use adequate timeouts for first-use calls that trigger cache loading","Fetch the current endpoint (List/Describe) first to confirm the target exists and capture its version","Retry updates; the cache load is lazy and succeeds once persistence recovers"],"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"}