github/copilot-sdk · error

User input requested but no handler registered

Error message

User input requested but no handler registered

What it means

Thrown by CopilotSession._handleUserInputRequest when the host requests user input but the application never registered a userInputHandler. Without a handler the SDK has no way to obtain a user response, so it throws instead of hanging or returning a bogus answer.

Solutions

1. Register a user input handler on the session (set userInputHandler via the provided API) before handling requests
2. If interactivity is not possible, register a stub handler that returns a default/denial UserInputResponse
3. Verify the handler is registered on the same session instance receiving the request

Example fix

// before
const session = new CopilotSession(...); // no handler
// after
const session = new CopilotSession(...);
session.setUserInputHandler(async (request, { sessionId }) => ({
  action: "respond",
  value: await promptUser(request),
}));

if (typeof session.getUserInputHandler !== "function" || session.getUserInputHandler() == null) {
  session.setUserInputHandler(defaultHandler);
}

try {
  await session._handleUserInputRequest(request);
} catch (err) {
  if (err?.message === "User input requested but no handler registered") {
    return { action: "reject", reason: "no interactive handler available" };
  }
  throw err;
}

When it happens

Trigger: Host sends a user-input request to a session where no userInputHandler was registered; application forgot to call the handler-registration API; handler registered on a different session instance.

Common situations: Running the SDK in an automated/CI context where interactive input was never wired; onboarding code samples that omit user-input registration; session recreation that lost the previously registered handler.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• User input requested but no handler registered
• canvas_action_no_handler
• User input handler error
• No user input handler registered
• Request handler must return a JSON-serializable value, got

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

Appendix: source

Thrown at nodejs/src/session.ts:1953

                // No callback for this section — pass through unchanged
                result[sectionId] = { content };
            }
        }

        return { sections: result };
    }

    /**
     * Handles a user input request from the Copilot CLI.
     *
     * @param request - The user input request data from the CLI
     * @returns A promise that resolves with the user's response
     * @internal This method is for internal use by the SDK.
     */
    async _handleUserInputRequest(request: unknown): Promise<UserInputResponse> {
        if (!this.userInputHandler) {
            // No handler registered, throw error
            throw new Error("User input requested but no handler registered");
        }

        try {
            const result = await this.userInputHandler(request as UserInputRequest, {
                sessionId: this.sessionId,
            });
            return result;
        } catch (error) {
            // Handler failed, rethrow
            throw error;
        }
    }

    /**
     * Handles a hooks invocation from the Copilot CLI.
     *
     * @param hookType - The type of hook being invoked
     * @param input - The input data for the hook

View on GitHub (pinned to cd8cf15dc3)