What causes "error loading nexus endpoint cache: %w" in temporalio/temporal?

Retry the UpdateNexusEndpoint call after the persistence layer recovers

error loading nexus endpoint cache: %w

Error message

error loading nexus endpoint cache: %w

What it means

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.

Source

Thrown at service/matching/nexus_endpoint_client.go:143

	m.insertEndpointLocked(entry)
	ch := m.tableVersionChanged
	m.tableVersionChanged = make(chan struct{})
	close(ch)

	return &matchingservice.CreateNexusEndpointResponse{
		Entry: entry,
	}, nil
}

func (m *nexusEndpointClient) UpdateNexusEndpoint(
	ctx context.Context,
	request *internalUpdateNexusEndpointRequest,
) (*matchingservice.UpdateNexusEndpointResponse, error) {
	if !m.hasLoadedEndpoints.Load() {
		// Endpoints must be loaded into memory before Update, since we need to check the previous entry and we need the
		// last known table version to update persistence.
		if err := m.loadEndpoints(ctx); err != nil {
			return nil, fmt.Errorf("error loading nexus endpoint cache: %w", err)
		}
	}

	m.Lock()
	defer m.Unlock()

	previous, exists := m.endpointsByID[request.endpointID]
	if !exists {
		return nil, serviceerror.NewNotFoundf("error updating Nexus endpoint. endpoint ID %v not found", request.endpointID)
	}

	if request.version != previous.Version {
		return nil, serviceerror.NewFailedPreconditionf("nexus endpoint version mismatch. received: %v expected %v", request.version, previous.Version)
	}

	entry := &persistencespb.NexusEndpointEntry{
		Version: previous.Version,
		Id:      previous.Id,

View on GitHub (pinned to bde624efd1)

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)

Defensive patterns

Strategy: retry

Try / catch

resp, err := client.MatchingClient().UpdateNexusEndpoint(ctx, req)
if err != nil && isTransient(err) {
	// backoff and retry; cache load will be re-attempted
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Related errors

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