{"record":{"id":"442f71b90cb46db8","repo":"langchain-ai/langchain","slug":"parameters-invalid-model-kwargs-should-be-specif","errorCode":null,"errorMessage":"Parameters {invalid_model_kwargs} should be specified explicitly. Instead they were passed in as part of `model_kwargs` parameter.","messagePattern":"Parameters (.+?) should be specified explicitly\\. Instead they were passed in as part of `model_kwargs` parameter\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/utils/utils.py","lineNumber":307,"sourceCode":"            msg = f\"Found {field_name} supplied twice.\"\n            raise ValueError(msg)\n        if field_name not in all_required_field_names:\n            warnings.warn(\n                f\"\"\"WARNING! {field_name} is not default parameter.\n                {field_name} was transferred to model_kwargs.\n                Please confirm that {field_name} is what you intended.\"\"\",\n                stacklevel=7,\n            )\n            extra_kwargs[field_name] = values.pop(field_name)\n\n    # DON'T USE! Kept for backwards-compatibility but should never have been public.\n    invalid_model_kwargs = all_required_field_names.intersection(extra_kwargs.keys())\n    if invalid_model_kwargs:\n        msg = (\n            f\"Parameters {invalid_model_kwargs} should be specified explicitly. \"\n            f\"Instead they were passed in as part of `model_kwargs` parameter.\"\n        )\n        raise ValueError(msg)\n\n    # DON'T USE! Kept for backwards-compatibility but should never have been public.\n    return extra_kwargs\n\n\ndef convert_to_secret_str(value: SecretStr | str) -> SecretStr:\n    \"\"\"Convert a string to a `SecretStr` if needed.\n\n    Args:\n        value: The value to convert.\n\n    Returns:\n        The `SecretStr` value.\n    \"\"\"\n    if isinstance(value, SecretStr):\n        return value\n    return SecretStr(value)\n","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/utils/utils.py#L289-L325","documentation":"Raised by the kwargs-filtering helper when `model_kwargs` contains keys that are already declared, recognized fields of the model (`all_required_field_names`). Recognized parameters must be passed explicitly so they are typed, validated, and traced correctly; smuggling them through `model_kwargs` bypasses that contract and LangChain rejects it.","triggerScenarios":"Passing known model parameters inside `model_kwargs`, e.g. `ChatOpenAI(model_kwargs={'model': 'gpt-4o', 'api_key': ...})` where `model` and `api_key` are declared fields of the class. Any intersection between `model_kwargs` keys and the model's declared field names triggers it.","commonSituations":"Treating `model_kwargs` as a generic catch-all for the whole provider request; migrating code from raw OpenAI SDK calls where everything went into one dict; a field being promoted from unknown to declared after an upgrade, so previously-tolerated `model_kwargs` entries now intersect with field names.","solutions":["Move every key named in the error message out of `model_kwargs` into an explicit constructor argument.","If a key is genuinely provider-specific and not a declared field, keep only those keys in `model_kwargs`.","Programmatically split a raw dict: `known = {k: v for k, v in raw.items() if k in declared_fields}; extra = {k: v for k, v in raw.items() if k not in declared_fields}` and pass each to the right place."],"exampleFix":"# before\nllm = ChatOpenAI(model_kwargs={\"model\": \"gpt-4o\", \"logprobs\": True})\n\n# after\nllm = ChatOpenAI(model=\"gpt-4o\", model_kwargs={\"logprobs\": True})","handlingStrategy":"validation","validationCode":"from pydantic import BaseModel\n\ndef split_for_constructor(cls: type[BaseModel], raw: dict) -> tuple[dict, dict]:\n    \"\"\"Split a raw dict into (explicit kwargs, model_kwargs) without overlap.\"\"\"\n    fields = set(cls.model_fields)\n    explicit = {k: v for k, v in raw.items() if k in fields}\n    extras = {k: v for k, v in raw.items() if k not in fields}\n    return explicit, extras","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use `model_fields` to route each key to either an explicit argument or `model_kwargs`, never both.","After upgrading an integration, diff its declared fields against your `model_kwargs` keys.","Reserve `model_kwargs` strictly for provider-specific options the wrapper does not model."],"tags":["configuration","pydantic","chat-model"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}