babalae/better-genshin-impact · warning · InvalidOperationException

当前尚未连接 BetterGI 根实例。

Error message

当前尚未连接 BetterGI 根实例。

What it means

Thrown by GetRequiredRootConnection() when _rootConnection is null. This private helper is called by GetVisibleWebViewsAsync and SendWebViewMessageAsync on non-Primary instances (ChildSession/WebView) to obtain the connection to the root. A null value means RootConnectionLoopAsync has not yet established a connection, or the previous connection was lost and the reconnect hasn't succeeded.

Source

Thrown at BetterGenshinImpact/Service/Instance/InstanceService.cs:543

                if (connection is not null)
                {
                    await connection.DisposeAsync().ConfigureAwait(false);
                }
            }

            if (!cancellationToken.IsCancellationRequested)
            {
                await Task.Delay(ReconnectDelay, cancellationToken).ConfigureAwait(false);
            }
        }
    }

    private InstanceConnection GetRequiredRootConnection()
    {
        lock (_rootConnectionLock)
        {
            return _rootConnection
                   ?? throw new InvalidOperationException("当前尚未连接 BetterGI 根实例。");
        }
    }

    private void EnqueueActivation(string[] args)
    {
        lock (_activationLock)
        {
            if (!_applicationReady)
            {
                _pendingActivations.Enqueue(args);
                return;
            }
        }

        DispatchActivation(args);
    }

    private void DispatchActivation(string[] args)

View on GitHub (pinned to a7cb36712d)

Solutions

1. Wait for the root connection to be established before issuing IPC requests — add an awaitable signal or check IsRootConnectionAvailable before calling.
2. Catch InvalidOperationException and show a user-facing message ('正在连接 BetterGI 根实例，请稍候') with a retry option.
3. If the root is not running, guide the user to start the main BetterGI instance first.
4. Consider exposing an IsRootConnectionEstablished property backed by _rootConnection != null for callers to check.

Example fix

// before
var rootConnection = GetRequiredRootConnection();
var response = await rootConnection.SendRequestAsync(...);

// after — caller-side guard
if (_rootConnection is null)
{
    throw new InvalidOperationException("正在连接 BetterGI 根实例，请稍后重试。");
}
var rootConnection = GetRequiredRootConnection();

// Check root connection availability before calling IPC methods (non-Primary only)
// Add a public property to InstanceService:
// public bool IsRootConnectionEstablished { get { lock(_rootConnectionLock) { return _rootConnection != null; } } }

if (!instanceService.IsRootConnectionEstablished)
{
    // Show 'connecting' state to user, retry later
    return;
}

try
{
    var result = await instanceService.GetVisibleWebViewsAsync(cancellationToken);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("尚未连接"))
{
    // Root not yet connected — retry or inform user
}

When it happens

Trigger: A ChildSession or WebView instance calls GetVisibleWebViewsAsync or SendWebViewMessageAsync before RootConnectionLoopAsync completes its first connection.open handshake, or during a reconnect gap after the previous root connection dropped. The reconnect loop waits ReconnectDelay (1 second) between attempts, creating windows where _rootConnection is null.

Common situations: Calling IPC methods during startup before the root connection is established; the root process is not running (so ConnectAsync fails and the loop retries); the root connection dropped and the 1-second reconnect delay hasn't elapsed; a race between the UI thread calling an IPC method and the background reconnect loop.

Related errors

• 根实例连接响应缺少数据。
• 根实例分配了不匹配的客户端类型：{openResponse.AssignedType}。
• 根实例连接在完成登记前已经关闭。
• 根实例拒绝连接。
• 根实例连接响应缺少数据。

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