What causes "未能返回主界面" in babalae/better-genshin-impact?

Make sure the game is in an ESCAPABLE state (open world, not in a cutscene/domain) before calling SwitchPartyTask.Start.

babalae/better-genshin-impact · error · InvalidOperationException

未能返回主界面

Error message

未能返回主界面

What it means

In SwitchPartyTask.Start, when not already on the party-view UI and not on the main UI, it runs _returnMainUiTask.Start then re-checks Bv.IsInMainUi. If still not on the main UI it throws InvalidOperationException — the prerequisite for opening the party screen is missing.

Source

Thrown at BetterGenshinImpact/GameTask/Common/Job/SwitchPartyTask.cs:47

    public async Task<bool> Start(string partyName, CancellationToken ct)
    {
        bool isInPartyViewUi = false;

        Logger.LogInformation("尝试切换至队伍: {Name}", partyName);
        using var ra1 = CaptureToRectArea();

        if (!Bv.IsInPartyViewUi(ra1))
        {
            isInPartyViewUi = true;
            // 如果不在主界面，则返回主界面
            if (!Bv.IsInMainUi(ra1))
            {
                await _returnMainUiTask.Start(ct);
                await Delay(200, ct);
                using var raAfterMain = CaptureToRectArea();
                if (!Bv.IsInMainUi(raAfterMain))
                {
                    throw new InvalidOperationException("未能返回主界面");
                }
            }

            // 尝试打开队伍配置页面
            const int maxAttempts = 2;
            bool isOpened = false;
            for (int attempt = 1; attempt <= maxAttempts; attempt++)
            {
                Simulation.SendInput.SimulateAction(GIActions.OpenPartySetupScreen);

                // 考虑加载时间 2s，共检查 4.2s，如果失败则抛出异常

                for (int i = 0; i < 7; i++) // 检查 7 次
                {
                    await Delay(600, ct);
                    using var raCheck = CaptureToRectArea();
                    if (Bv.IsInPartyViewUi(raCheck))
                    {

View on GitHub (pinned to a7cb36712d)

Solutions

Make sure the game is in an ESCAPABLE state (open world, not in a cutscene/domain) before calling SwitchPartyTask.Start.
Verify Bv.IsInMainUi detectors match the current game version.
Increase the Delay(200) after ReturnMainUiTask or retry the return once before giving up.
If the screen is genuinely stuck, the user must manually return to the main UI first.

Defensive patterns

Strategy: try-catch

Validate before calling

if (!Bv.IsInMainUi(CaptureToRectArea()))
{
    await _returnMainUiTask.Start(ct);
    if (!Bv.IsInMainUi(CaptureToRectArea()))
        throw new InvalidOperationException("游戏未处于可打开队伍界面的主界面状态");
}

Try / catch

try { await partyTask.Start(partyName, ct); }
catch (InvalidOperationException ex) when (ex.Message == "未能返回主界面")
{ _logger.LogError(ex, "无法返回主界面：游戏可能处于过场/秘境，请手动回到主界面"); }

Prevention

Call SwitchPartyTask only from an escapable open-world state.
Keep Bv.IsInMainUi detectors current with the game version.
Retry the return-to-main-UI once before aborting.

When it happens

Trigger: Bv.IsInPartyViewUi false AND Bv.IsInMainUi false initially; after _returnMainUiTask.Start(ct) + Delay(200), a fresh capture still fails Bv.IsInMainUi.

Common situations: The game is stuck on a loading screen, a cutscene, an unescapable dialog, or a domain; ReturnMainUiTask could not escape the current screen; capture is stale; a game version changed the main-UI detection markers Bv.IsInMainUi relies on.

Related errors

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