{"record":{"id":"41a4a678ed7fa22d","repo":"babalae/better-genshin-impact","slug":"bettergi-41a4a6","errorCode":null,"errorMessage":"当前尚未连接 BetterGI 根实例。","messagePattern":"当前尚未连接 BetterGI 根实例。","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"warning","filePath":"BetterGenshinImpact/Service/Instance/InstanceService.cs","lineNumber":543,"sourceCode":"                if (connection is not null)\n                {\n                    await connection.DisposeAsync().ConfigureAwait(false);\n                }\n            }\n\n            if (!cancellationToken.IsCancellationRequested)\n            {\n                await Task.Delay(ReconnectDelay, cancellationToken).ConfigureAwait(false);\n            }\n        }\n    }\n\n    private InstanceConnection GetRequiredRootConnection()\n    {\n        lock (_rootConnectionLock)\n        {\n            return _rootConnection\n                   ?? throw new InvalidOperationException(\"当前尚未连接 BetterGI 根实例。\");\n        }\n    }\n\n    private void EnqueueActivation(string[] args)\n    {\n        lock (_activationLock)\n        {\n            if (!_applicationReady)\n            {\n                _pendingActivations.Enqueue(args);\n                return;\n            }\n        }\n\n        DispatchActivation(args);\n    }\n\n    private void DispatchActivation(string[] args)","sourceCodeStart":525,"sourceCodeEnd":561,"githubUrl":"https://github.com/babalae/better-genshin-impact/blob/a7cb36712dcb409be610257d877fcea3597e9d6b/BetterGenshinImpact/Service/Instance/InstanceService.cs#L525-L561","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wait for the root connection to be established before issuing IPC requests — add an awaitable signal or check IsRootConnectionAvailable before calling.","Catch InvalidOperationException and show a user-facing message ('正在连接 BetterGI 根实例，请稍候') with a retry option.","If the root is not running, guide the user to start the main BetterGI instance first.","Consider exposing an IsRootConnectionEstablished property backed by _rootConnection != null for callers to check."],"exampleFix":"// before\nvar rootConnection = GetRequiredRootConnection();\nvar response = await rootConnection.SendRequestAsync(...);\n\n// after — caller-side guard\nif (_rootConnection is null)\n{\n    throw new InvalidOperationException(\"正在连接 BetterGI 根实例，请稍后重试。\");\n}\nvar rootConnection = GetRequiredRootConnection();","handlingStrategy":"validation","validationCode":"// Check root connection availability before calling IPC methods (non-Primary only)\n// Add a public property to InstanceService:\n// public bool IsRootConnectionEstablished { get { lock(_rootConnectionLock) { return _rootConnection != null; } } }\n\nif (!instanceService.IsRootConnectionEstablished)\n{\n    // Show 'connecting' state to user, retry later\n    return;\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    var result = await instanceService.GetVisibleWebViewsAsync(cancellationToken);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"尚未连接\"))\n{\n    // Root not yet connected — retry or inform user\n}","preventionTips":["Do not call root-dependent IPC methods during startup before the connection loop completes.","Expose an IsRootConnectionEstablished property for callers to check.","Handle the reconnecting state in UI gracefully."],"tags":["ipc","connection-state","root-connection","timing","reconnect"],"backgroundTag":null,"analyzedSha":"a7cb36712dcb409be610257d877fcea3597e9d6b","analyzedAt":"2026-08-13T16:44:57.548Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}