github/copilot-sdk · error · IllegalArgumentException

options must specify a model

Error message

options must specify a model

What it means

CopilotSession.setModel(SetModelOptions) requires the options object to carry a non-null model identifier; when options.getModel() returns null it throws IllegalArgumentException('options must specify a model'). The model field is mandatory because the underlying SessionModelSwitchToParams RPC needs an explicit target model.

Solutions

1. Set the model field on SetModelOptions before calling setModel (e.g. options.setModel("gpt-5")).
2. If you only intend to adjust auto tier/reasoning settings, still supply the current model explicitly.
3. Add a caller-side guard that rejects options with a null model.

Example fix

// before
session.setModel(new SetModelOptions().setAutoTier("high")); // model missing
// after
session.setModel(new SetModelOptions()
        .setModel("gpt-5")
        .setAutoTier("high"));

if (options == null || options.getModel() == null) {
    throw new IllegalArgumentException("setModel requires options with a model");
}

boolean hasModel(com.github.copilot.rpc.SetModelOptions o) { return o != null && o.getModel() != null && !o.getModel().isBlank(); }

try {
    session.setModel(options);
} catch (IllegalArgumentException e) {
    LOG.warning("model not set: " + e.getMessage());
}

When it happens

Trigger: Calling session.setModel(new SetModelOptions()) or a builder-produced options object without ever setting the model (CopilotSession.java:2240).

Common situations: Code that intends to change only autoTier or reasoningSummary builds SetModelOptions but forgets that model is still required; also common when the model comes from nullable config and is forwarded unchanged.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• options must not be null
• setModel cannot combine an explicit autoTier with…
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required
• sessionFs.conventions must be either 'windows' or 'posix'

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

Appendix: source

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

     *
     * @param options
     *            the switch settings; the model ID is required
     * @return a future that completes when the model switch is acknowledged
     * @throws IllegalArgumentException
     *             if {@code options} is {@code null}, if it carries no model ID, or
     *             if it requests both an explicit Auto tier and a return to
     *             provider-default Auto routing
     * @throws IllegalStateException
     *             if this session has been terminated
     * @since 1.6.0
     */
    public CompletableFuture<Void> setModel(com.github.copilot.rpc.SetModelOptions options) {
        ensureNotTerminated();
        if (options == null) {
            throw new IllegalArgumentException("options must not be null");
        }
        if (options.getModel() == null) {
            throw new IllegalArgumentException("options must specify a model");
        }
        if (options.getAutoTier() != null && options.isResetAutoTier()) {
            throw new IllegalArgumentException(
                    "setModel cannot combine an explicit autoTier with resetAutoTier; choose one");
        }
        var generatedReasoningSummary = options.getReasoningSummary() == null
                ? null
                : com.github.copilot.generated.rpc.ReasoningSummary.fromValue(options.getReasoningSummary());
        var params = new SessionModelSwitchToParams(sessionId, options.getModel(),
                toGeneratedAutoTier(options.getAutoTier()), options.getReasoningEffort(), generatedReasoningSummary,
                null, toGeneratedCapabilities(options.getModelCapabilities()), null, null, null, null, null, null, null,
                null, null);
        if (!options.isResetAutoTier()) {
            return getRpc().model.switchTo(params).thenApply(r -> null);
        }
        // The generated params record omits null properties, but returning to
        // provider-default Auto routing requires sending an explicit null tier, so
        // build the payload directly and reinstate the null.

View on GitHub (pinned to cd8cf15dc3)