{"record":{"id":"678af3ceac4dd179","repo":"github/copilot-sdk","slug":"options-must-specify-a-model","errorCode":null,"errorMessage":"options must specify a model","messagePattern":"options must specify a model","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotSession.java","lineNumber":2240,"sourceCode":"     *\n     * @param options\n     *            the switch settings; the model ID is required\n     * @return a future that completes when the model switch is acknowledged\n     * @throws IllegalArgumentException\n     *             if {@code options} is {@code null}, if it carries no model ID, or\n     *             if it requests both an explicit Auto tier and a return to\n     *             provider-default Auto routing\n     * @throws IllegalStateException\n     *             if this session has been terminated\n     * @since 1.6.0\n     */\n    public CompletableFuture<Void> setModel(com.github.copilot.rpc.SetModelOptions options) {\n        ensureNotTerminated();\n        if (options == null) {\n            throw new IllegalArgumentException(\"options must not be null\");\n        }\n        if (options.getModel() == null) {\n            throw new IllegalArgumentException(\"options must specify a model\");\n        }\n        if (options.getAutoTier() != null && options.isResetAutoTier()) {\n            throw new IllegalArgumentException(\n                    \"setModel cannot combine an explicit autoTier with resetAutoTier; choose one\");\n        }\n        var generatedReasoningSummary = options.getReasoningSummary() == null\n                ? null\n                : com.github.copilot.generated.rpc.ReasoningSummary.fromValue(options.getReasoningSummary());\n        var params = new SessionModelSwitchToParams(sessionId, options.getModel(),\n                toGeneratedAutoTier(options.getAutoTier()), options.getReasoningEffort(), generatedReasoningSummary,\n                null, toGeneratedCapabilities(options.getModelCapabilities()), null, null, null, null, null, null, null,\n                null, null);\n        if (!options.isResetAutoTier()) {\n            return getRpc().model.switchTo(params).thenApply(r -> null);\n        }\n        // The generated params record omits null properties, but returning to\n        // provider-default Auto routing requires sending an explicit null tier, so\n        // build the payload directly and reinstate the null.","sourceCodeStart":2222,"sourceCodeEnd":2258,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotSession.java#L2222-L2258","documentation":"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.","triggerScenarios":"Calling session.setModel(new SetModelOptions()) or a builder-produced options object without ever setting the model (CopilotSession.java:2240).","commonSituations":"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.","solutions":["Set the model field on SetModelOptions before calling setModel (e.g. options.setModel(\"gpt-5\")).","If you only intend to adjust auto tier/reasoning settings, still supply the current model explicitly.","Add a caller-side guard that rejects options with a null model."],"exampleFix":"// before\nsession.setModel(new SetModelOptions().setAutoTier(\"high\")); // model missing\n// after\nsession.setModel(new SetModelOptions()\n        .setModel(\"gpt-5\")\n        .setAutoTier(\"high\"));","handlingStrategy":"validation","validationCode":"if (options == null || options.getModel() == null) {\n    throw new IllegalArgumentException(\"setModel requires options with a model\");\n}","typeGuard":"boolean hasModel(com.github.copilot.rpc.SetModelOptions o) { return o != null && o.getModel() != null && !o.getModel().isBlank(); }","tryCatchPattern":"try {\n    session.setModel(options);\n} catch (IllegalArgumentException e) {\n    LOG.warning(\"model not set: \" + e.getMessage());\n}","preventionTips":["Always set the model field, even when only changing autoTier or reasoningSummary.","Centralize options construction so model is mandatory at build time.","Validate config-supplied model strings before wrapping them in SetModelOptions."],"tags":["validation","missing-field","set-model"],"backgroundTag":"missing-required-argument","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"}