langchain-ai/deepagents · error · ValueError

Invalid JSON in --model-params: {json_str!r}. Expected forma

Error message

Invalid JSON in --model-params: {json_str!r}. Expected format: --model-params '{"key": "value"}'

What it means

`_extract_model_params_flag` parses the `--model-params` CLI value with `json.loads`. If parsing fails (JSONDecodeError), it raises this ValueError showing the offending input and the expected quoting format, so the user knows the shell mangled or malformed their JSON rather than silently dropping the flag.

Source

Thrown at libs/code/deepagents_code/app.py:1986

            msg = "Unbalanced braces in --model-params value"
            raise ValueError(msg)
        json_str = after[: end + 1]
        rest = after[end + 1 :].lstrip()
    else:
        # Non-brace, non-quoted — take the next whitespace-delimited token.
        parts = after.split(None, 1)
        json_str = parts[0]
        rest = parts[1] if len(parts) > 1 else ""

    remaining = f"{before} {rest}".strip()
    try:
        params = json.loads(json_str)
    except json.JSONDecodeError:
        msg = (
            f"Invalid JSON in --model-params: {json_str!r}. "
            'Expected format: --model-params \'{"key": "value"}\''
        )
        raise ValueError(msg) from None
    if not isinstance(params, dict):
        msg = "--model-params must be a JSON object, got " + type(params).__name__
        raise TypeError(msg)
    return remaining, params


def _format_model_params(extra_kwargs: dict[str, Any] | None) -> str:
    """Render `--model-params` as a stable, key-sorted JSON suffix.

    Args:
        extra_kwargs: The parsed `--model-params` payload, or `None`.

    Returns:
        ` with model params {json}` when `extra_kwargs` is non-empty;
        otherwise an empty string so callers can unconditionally concatenate.
    """
    if not extra_kwargs:
        return ""

View on GitHub (pinned to a1af029e6e)

Solutions

1. Wrap the whole JSON value in single quotes: --model-params '{"temperature": 0}'
2. Validate the JSON first with `python -c "import json;json.loads('<value>')"` before passing it
3. On Windows cmd/PowerShell, use escaped double quotes: --model-params "{\"temperature\": 0}"
4. If building the flag programmatically, use json.dumps on the dict instead of string interpolation

Example fix

// before
--model-params {"temperature": 0}
// after
--model-params '{"temperature": 0}'

import json
params = json.loads(json_str)  # raises before the call if malformed
assert isinstance(params, dict)
# then pass json.dumps(params) as the --model-params value

def is_json_object(s: str) -> bool:
    try:
        return isinstance(json.loads(s), dict)
    except json.JSONDecodeError:
        return False

try:
    remaining, params = _extract_model_params_flag(argv)
except ValueError as exc:
    print(f"usage: {exc}")  # shows the expected format
    sys.exit(2)

When it happens

Trigger: Invoking the CLI with `--model-params <value>` where the value is not valid JSON: unbalanced braces, single-quoted JSON, keys/values missing quotes, or shell-stripped quotes (e.g. `--model-params {"key": "value"}` unquoted so the shell eats the braces).

Common situations: Developers pasting JSON examples into shells where outer quotes are consumed; Windows cmd quoting differences; using single quotes inside the JSON; forgetting that the whole argument must be one shell word.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• --model-params must be a JSON object, got {type}
• --max-content must be positive
• --list must be positive
• dcode: {message}
• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/884e2f12119b6b93. Report an issue: GitHub.