egametang/ET · critical · RpcException

ERR_LocationPrimaryUnavailable

ERR_LocationPrimaryUnavailable

Error message

location service metadata missing scene: {serviceInfo?.SceneName}

What it means

Thrown by LocationPrimaryHelper.GetPriorityId when the ServiceInfo object is null or its Metadata dictionary is null. Every Location scene must register with service discovery carrying a Metadata dictionary that includes PriorityId (set in FiberInit_Location.cs:24-27). A null ServiceInfo or null Metadata means the registration was malformed or incomplete.

Source

Thrown at Packages/cn.etetet.actorlocation/Scripts/Hotfix/Server/LocationPrimaryHelper.cs:12

using System;
using System.Collections.Generic;

namespace ET.Server
{
    public static class LocationPrimaryHelper
    {
        public static ulong GetPriorityId(ServiceInfo serviceInfo)
        {
            if (serviceInfo?.Metadata == null)
            {
                throw new RpcException(ErrorCode.ERR_LocationPrimaryUnavailable,
                    $"location service metadata missing scene: {serviceInfo?.SceneName}");
            }

            if (!serviceInfo.Metadata.TryGetValue(ServiceMetaKey.PriorityId, out string rawPriorityId)
                || string.IsNullOrWhiteSpace(rawPriorityId))
            {
                throw new RpcException(ErrorCode.ERR_LocationPrimaryUnavailable,
                    $"location service priority missing scene: {serviceInfo.SceneName}");
            }

            if (ulong.TryParse(rawPriorityId, out ulong priorityId))
            {
                return priorityId;
            }

            if (!long.TryParse(rawPriorityId, out long signedPriorityId))
            {
                throw new RpcException(ErrorCode.ERR_LocationPrimaryUnavailable,

View on GitHub (pinned to 5cab01f7a8)

Solutions

Ensure every Location scene's FiberInit registers with Metadata containing PriorityId, as FiberInit_Location.cs:24-27 does.
Check service discovery registration logs to verify Metadata was included.
If a node is registering with incomplete metadata, fix its FiberInit or registration call before it joins the cluster.

Example fix

// before -- registration without metadata
await serviceDiscoveryProxy.RegisterToServiceDiscovery(new StringKV());

// after -- include PriorityId in metadata
await serviceDiscoveryProxy.RegisterToServiceDiscovery(new StringKV
{
    { ServiceMetaKey.PriorityId, locationComponent.Id.ToString() }
});

Defensive patterns

Strategy: validation

Validate before calling

// Validate ServiceInfo before primary election
foreach (ServiceInfo si in serviceInfos)
{
    if (si?.Metadata == null)
    {
        Log.Error($"Location scene {si?.SceneName} has null metadata -- skipping");
        continue;
    }
}

Type guard

static bool HasValidMetadata(ServiceInfo si) => si?.Metadata != null;

Try / catch

try
{
    string primary = locationProxy.GetPrimaryLocationSceneName();
}
catch (RpcException e) when (e.Error == ErrorCode.ERR_LocationPrimaryUnavailable)
{
    Log.Error($"Primary election failed: {e.Message}");
}

Prevention

Ensure FiberInit_Location runs on every Location scene -- it sets Metadata with PriorityId.
Validate service discovery entries after registration to catch missing metadata early.
Monitor service discovery for entries with null or incomplete metadata.

When it happens

Trigger: GetPriorityId(serviceInfo) is called during SelectStablePrimaryServiceInfo when iterating discovered Location scenes, and one of them has a null Metadata. This propagates through GetPrimaryLocationSceneName in the proxy, which catches it as ERR_LocationPrimaryUnavailable and retries/clears primary.

Common situations: A Location scene registered with service discovery but its Metadata was not populated (custom FiberInit that skips the Metadata setup); a corrupted or partial ServiceInfo entity deserialized from DB/network with Metadata lost; version mismatch where an older client registers without Metadata.

Related errors

AI-assisted analysis of egametang/ET@5cab01f7a8 (2026-08-13). Data as JSON: /api/errors/da79cdcb6d1daaa8. Report an issue: GitHub.