langchain-ai/deepagents · error · TypeError

Store item `content` must be a `str` or legacy `list[str]`,

Error message

Store item `content` must be a `str` or legacy `list[str]`, got {type(raw_content).__name__}.

What it means

Store item `content` must be either a `str` or a legacy `list[str]` (joined with newlines during conversion). Any other type (bytes, dict, int, or a list with non-string elements) is rejected with a TypeError naming the offending Python type.

Source

Thrown at libs/deepagents/deepagents/backends/store.py:196

                content is joined without modifying the persisted item. Includes
                `created_at` and `modified_at` when present.

        Raises:
            ValueError: If the store item has no content.
            TypeError: If content is neither a string nor a legacy list of strings.
        """
        raw_content = store_item.value.get("content")
        if raw_content is None:
            msg = f"Store item does not contain valid content field. Got: {store_item.value.keys()}"
            raise ValueError(msg)

        if isinstance(raw_content, list) and all(isinstance(line, str) for line in raw_content):
            content = "\n".join(raw_content)
        elif isinstance(raw_content, str):
            content = raw_content
        else:
            msg = f"Store item `content` must be a `str` or legacy `list[str]`, got {type(raw_content).__name__}."
            raise TypeError(msg)

        result = FileData(
            content=content,
            encoding=store_item.value.get("encoding", "utf-8"),
        )
        if "created_at" in store_item.value and isinstance(store_item.value["created_at"], str):
            result["created_at"] = store_item.value["created_at"]
        if "modified_at" in store_item.value and isinstance(store_item.value["modified_at"], str):
            result["modified_at"] = store_item.value["modified_at"]
        return result

    def _convert_file_data_to_store_value(self, file_data: FileData) -> dict[str, Any]:
        """Convert `FileData` to a dict suitable for `store.put()`.

        Args:
            file_data: The `FileData` to convert.

        Returns:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Write `content` as a `str` (or list of str lines) when putting items into the store
2. Decode bytes with `.decode('utf-8')` before storing; serialize dicts with json.dumps()
3. Normalize mixed lists to strings (`[str(x) for x in lines]`) before writing
4. Add a write-side check that rejects non-str/list[str] content early

Example fix

// before
store.put(ns, key, {'content': b'hello'})
// after
store.put(ns, key, {'content': b'hello'.decode('utf-8')})

def normalize_content(content):
    if isinstance(content, bytes):
        return content.decode('utf-8')
    if isinstance(content, (dict, list)) and not all(isinstance(l, str) for l in (content if isinstance(content, list) else [])):
        import json
        return json.dumps(content)
    return content
store.put(ns, key, {'content': normalize_content(raw)})

def is_valid_content(content: object) -> bool:
    if isinstance(content, str):
        return True
    return isinstance(content, list) and all(isinstance(l, str) for l in content)

try:
    data = backend.read('/a.txt')
except TypeError as exc:
    if 'must be a `str` or legacy `list[str]`' in str(exc):
        rewrite_item_with_valid_content('/a.txt')
    else:
        raise

When it happens

Trigger: Writing store items whose `content` is bytes, a dict, an int, or a mixed list like `['a', 2]`, then reading them back through StoreBackend's `_convert_store_item_to_file_data`.

Common situations: Encoding text as bytes before storing; storing structured JSON payloads as dict content; mixed-type lists from unparsed user input; version drift where a newer writer changed the content type.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {prefix}.{name} must be a dictionary, got {type(values).__na
• Store item does not contain valid content field. Got: {store
• -32002
• Could not parse embedded resource block. Block expected eith
• {question_type} question {question_text!r} must not define '

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