babalae/better-genshin-impact · error · TimeoutException

切换到地表地图后校验超时

Error message

切换到地表地图后校验超时

What it means

Thrown by SwitchToGroundMapLayerIfNeeded when the verification loop times out (MapGroundLayerSwitchTimeoutMs) after clicking the ground-layer button. The method polls for the underground button to disappear (indicating successful switch to surface), but if it never disappears within the timeout, a TimeoutException is thrown.

Source

Thrown at BetterGenshinImpact/GameTask/AutoTrackPath/TpTask.cs:2534

                await Delay(retryInterval, ct);
                continue;
            }

            if (!layerSwitchClicked)
            {
                undergroundButton.Click();
                capture.MoveTo(capture.Width / 2, capture.Height / 2);
                layerSwitchClicked = true;
                await Delay(retryInterval, ct);
                continue;
            }

            await Delay(retryInterval, ct);
        }

        Logger.LogWarning("切换到地表地图后校验超时");
        throw new TimeoutException("切换到地表地图后校验超时");
    }

    public Task ClickTpPoint(
        ImageRegion imageRegion,
        GiTpPosition? targetTp = null,
        string mapName = "Teyvat",
        Rect bigMapInAllMapRect = default,
        double targetX = double.NaN,
        double targetY = double.NaN)
    {
        return ClickTpPoint(imageRegion, targetTp);
    }

    private async Task ClickTpPoint(
        ImageRegion imageRegion,
        GiTpPosition? targetTp)
    {
        var result = await HandleTeleportPanel(imageRegion, targetTp);

View on GitHub (pinned to a7cb36712d)

Solutions

1. Increase MapGroundLayerSwitchTimeoutMs to accommodate slower machines.
2. Verify the layer-switch button recognition assets match the current game UI.
3. Ensure the map is in a state where underground/ground layer switching is applicable.
4. Retry the operation; transient UI lag can cause a single timeout.
5. Check if the game is responsive and not in a loading state.

try
{
    await task.SwitchToGroundMapLayerIfNeeded();
}
catch (TimeoutException ex) when (ex.Message == "切换到地表地图后校验超时")
{
    Logger.LogWarning("Ground layer switch timed out. Retrying or skipping.");
    // Retry once or continue if ground layer is not critical
}

When it happens

Trigger: Called from SwitchToGroundMapLayerIfNeeded. The while-loop runs until stopwatch exceeds MapGroundLayerSwitchTimeoutMs. Either the MapUndergroundToGroundButton or MapUndergroundSwitchButton detection doesn't transition as expected after clicking.

Common situations: Map layer switch animation is slow or stuck; the ground-layer button recognition template doesn't match; the game is in a state where layer switching isn't available; UI lag delays the transition beyond the timeout.

Related errors

• 切换区域[{areaName}]失败
• Raw Input 采集线程初始化超过 {InitializationTimeout.TotalSeconds:0} 秒
• 超时未找到征讨之花领奖界面
• 关闭补充原粹树脂提示超时
• 识别骰子数量不正确,重试超时,停止自动打牌！

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/5b348e3eb26e3d77. Report an issue: GitHub.