babalae/better-genshin-impact · error · InvalidOperationException

根实例拒绝连接。

Error message

根实例拒绝连接。

What it means

Thrown when the root BetterGI instance responds to a connection.open request with Success != true but both ErrorMessage and ErrorCode are null/empty, so the fallback literal message is used. It indicates the root instance actively refused the connection but failed to populate an error detail.

Source

Thrown at BetterGenshinImpact/Service/Instance/InstanceBootstrap.cs:232

                        client,
                        timeout.Token).ConfigureAwait(false);
                    if (frame is null)
                    {
                        client.Dispose();
                        continue;
                    }

                    var response = InstanceIpcProtocol.ReadJson(frame.Value);
                    if (response.Operation != InstanceOperations.Response
                        || response.RequestId != request.RequestId)
                    {
                        client.Dispose();
                        continue;
                    }
                    if (response.Success != true)
                    {
                        client.Dispose();
                        throw new InvalidOperationException(
                            response.ErrorMessage ?? response.ErrorCode ?? "根实例拒绝连接。");
                    }

                    var openResponse =
                        response.Data?.ToObject<ConnectionOpenResponse>(
                            InstanceIpcProtocol.Serializer)
                        ?? throw new InvalidDataException("根实例连接响应缺少数据。");
                    return new InitialRootConnection(client, openResponse);
                }
                catch
                {
                    client.Dispose();
                    throw;
                }
            }
            catch (Exception exception) when (exception is IOException
                                              or UnauthorizedAccessException
                                              or TimeoutException

View on GitHub (pinned to a7cb36712d)

Solutions

1. Restart the root BetterGI instance — a degraded root is the most common cause.
2. Check the root instance's logs for the handler exception that produced the empty error.
3. Ensure both instances are the same BetterGI build to rule out protocol/handler mismatches.

try
{
    var connection = await TryOpenRootConnectionAsync(...);
}
catch (InvalidOperationException ex)
{
    logger.LogError(ex, "Root instance rejected connection: {Message}", ex.Message);
    // Suggest restarting the root instance.
}

When it happens

Trigger: The root instance's connection handler returned a Failure envelope with empty error fields, or a handler exception propagated without setting them. Possible causes: capacity limit reached, the request type is disallowed in the root's current state, or an internal handler bug.

Common situations: Root instance in a degraded state; a handler threw and the Failure was constructed without a message; concurrent instance limit; version skew where the root no longer understands the requested instance type.

Related errors

• 根实例连接响应缺少数据。
• 不支持的实例 IPC 版本：{envelope.Version}。
• 预期 JSON 帧，实际为 {frame.PayloadType}。
• 命名管道 JSON 消息为空。
• 预期相对鼠标帧，实际为 {frame.PayloadType}。

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