github/copilot-sdk · error · RuntimeException

Auto mode switch handler error

Error message

Auto mode switch handler error

What it means

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.

Solutions

1. Inspect the exception cause logged by CopilotSession and correct the failing code in your AutoModeSwitchHandler.
2. Validate/auto-derive the requested mode inside the handler, falling back to a safe default for unknown values.
3. Catch expected failures inside the handler and translate them into descriptive failed futures.

Example fix

// before
(request, invocation) -> applyMode(request.mode()); // throws for unknown mode
// after
(request, invocation) -> {
    try {
        return applyMode(request.mode());
    } catch (UnknownModeException e) {
        return applyMode(Mode.DEFAULT);
    }
};

Set<String> known = Set.of("off", "on", "auto");
if (request.mode() == null || !known.contains(request.mode())) {
    return CompletableFuture.failedFuture(new IllegalArgumentException("unknown mode: " + request.mode()));
}

boolean isKnownMode(String mode) { return mode != null && Set.of("off","on","auto").contains(mode); }

try {
    return applyMode(request.mode());
} catch (UnknownModeException e) {
    return applyMode(Mode.DEFAULT);
}

When it happens

Trigger: The handler registered for AutoModeSwitchInvocation (AutoModeSwitchHandler.handle) throws synchronously, or its returned CompletableFuture completes exceptionally (CopilotSession.java:1837).

Common situations: 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.

Related errors

• User input handler error
• Exit plan mode handler error
• invalid auto mode switch request payload
• workingDirectory is not supported with…
• env is not supported with RuntimeConnection.forInProcess()…

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/99a7de651fb25e26. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CopilotSession.java:1837

     * Handles an auto-mode-switch request from the Copilot CLI.
     * <p>
     * Called internally when the server sends an {@code autoModeSwitch.request}.
     *
     * @param request
     *            the auto-mode-switch request
     * @return a future that resolves with the user's decision
     */
    CompletableFuture<AutoModeSwitchResponse> handleAutoModeSwitchRequest(AutoModeSwitchRequest request) {
        AutoModeSwitchHandler handler = autoModeSwitchHandler.get();
        if (handler == null) {
            return CompletableFuture.completedFuture(AutoModeSwitchResponse.NO);
        }

        try {
            var invocation = new AutoModeSwitchInvocation().setSessionId(sessionId);
            return handler.handle(request, invocation).exceptionally(ex -> {
                LOG.log(Level.SEVERE, "Auto mode switch handler threw an exception", ex);
                throw new RuntimeException("Auto mode switch handler error", ex);
            });
        } catch (Exception e) {
            LOG.log(Level.SEVERE, "Failed to process auto mode switch request", e);
            return CompletableFuture.failedFuture(e);
        }
    }

    /**
     * Registers hook handlers for this session.
     * <p>
     * Called internally when creating or resuming a session with hooks.
     *
     * @param hooks
     *            the hooks configuration
     */
    void registerHooks(SessionHooks hooks) {
        hooksHandler.set(hooks);
    }

View on GitHub (pinned to cd8cf15dc3)