{"record":{"id":"99a7de651fb25e26","repo":"github/copilot-sdk","slug":"auto-mode-switch-handler-error","errorCode":null,"errorMessage":"Auto mode switch handler error","messagePattern":"Auto mode switch handler error","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotSession.java","lineNumber":1837,"sourceCode":"     * Handles an auto-mode-switch request from the Copilot CLI.\n     * <p>\n     * Called internally when the server sends an {@code autoModeSwitch.request}.\n     *\n     * @param request\n     *            the auto-mode-switch request\n     * @return a future that resolves with the user's decision\n     */\n    CompletableFuture<AutoModeSwitchResponse> handleAutoModeSwitchRequest(AutoModeSwitchRequest request) {\n        AutoModeSwitchHandler handler = autoModeSwitchHandler.get();\n        if (handler == null) {\n            return CompletableFuture.completedFuture(AutoModeSwitchResponse.NO);\n        }\n\n        try {\n            var invocation = new AutoModeSwitchInvocation().setSessionId(sessionId);\n            return handler.handle(request, invocation).exceptionally(ex -> {\n                LOG.log(Level.SEVERE, \"Auto mode switch handler threw an exception\", ex);\n                throw new RuntimeException(\"Auto mode switch handler error\", ex);\n            });\n        } catch (Exception e) {\n            LOG.log(Level.SEVERE, \"Failed to process auto mode switch request\", e);\n            return CompletableFuture.failedFuture(e);\n        }\n    }\n\n    /**\n     * Registers hook handlers for this session.\n     * <p>\n     * Called internally when creating or resuming a session with hooks.\n     *\n     * @param hooks\n     *            the hooks configuration\n     */\n    void registerHooks(SessionHooks hooks) {\n        hooksHandler.set(hooks);\n    }","sourceCodeStart":1819,"sourceCodeEnd":1855,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotSession.java#L1819-L1855","documentation":"CopilotSession invokes the registered auto-mode-switch handler and wraps any failure (thrown or via a failed future) into a RuntimeException carrying 'Auto mode switch handler error', logging the original exception at SEVERE first. The SDK is reporting that your handler, not the transport, failed while processing an auto-mode switch request.","triggerScenarios":"The handler registered for AutoModeSwitchInvocation (AutoModeSwitchHandler.handle) throws synchronously, or its returned CompletableFuture completes exceptionally (CopilotSession.java:1837).","commonSituations":"An auto-mode handler maintains per-mode configuration and throws on an unknown mode value sent by the client, or fails while updating external state during a mode switch.","solutions":["Inspect the exception cause logged by CopilotSession and correct the failing code in your AutoModeSwitchHandler.","Validate/auto-derive the requested mode inside the handler, falling back to a safe default for unknown values.","Catch expected failures inside the handler and translate them into descriptive failed futures."],"exampleFix":"// before\n(request, invocation) -> applyMode(request.mode()); // throws for unknown mode\n// after\n(request, invocation) -> {\n    try {\n        return applyMode(request.mode());\n    } catch (UnknownModeException e) {\n        return applyMode(Mode.DEFAULT);\n    }\n};","handlingStrategy":"validation","validationCode":"Set<String> known = Set.of(\"off\", \"on\", \"auto\");\nif (request.mode() == null || !known.contains(request.mode())) {\n    return CompletableFuture.failedFuture(new IllegalArgumentException(\"unknown mode: \" + request.mode()));\n}","typeGuard":"boolean isKnownMode(String mode) { return mode != null && Set.of(\"off\",\"on\",\"auto\").contains(mode); }","tryCatchPattern":"try {\n    return applyMode(request.mode());\n} catch (UnknownModeException e) {\n    return applyMode(Mode.DEFAULT);\n}","preventionTips":["Validate mode values against an allow-list before applying them.","Fall back to a safe default mode for unrecognized values.","Keep handler logic free of blocking I/O that can fail mid-switch."],"tags":["handler-exception","auto-mode","rpc"],"backgroundTag":"handler-exception","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}