huggingface/smolagents · error · SerializationError

Cannot serialize object: {e}

Error message

Cannot serialize object: {e}

What it means

SafeSerializer.dumps tried to serialize an object that is not JSON-safe and also could not be pickled (pickle raised PicklingError, TypeError, or AttributeError). The serializer's fallback chain is: JSON-safe types, then base64-pickled bytes with a 'pickle:' prefix; when both fail it raises this SerializationError. It usually means the object holds unpicklable state such as open file handles, sockets, threads, locks, lambdas, or modules.

Source

Thrown at src/smolagents/serialization.py:292

                json_safe = SafeSerializer.to_json_safe(obj)
                return SafeSerializer.SAFE_PREFIX + json.dumps(json_safe)
            except SerializationError:
                # Warn about insecure pickle usage
                import warnings

                warnings.warn(
                    "Falling back to insecure pickle serialization. "
                    "This is a security risk and will be removed in a future version. "
                    "Consider using only safe serializable types (primitives, lists, dicts, "
                    "numpy arrays, PIL images, datetime objects, dataclasses).",
                    FutureWarning,
                    stacklevel=2,
                )
                # Fallback to pickle (with prefix)
                try:
                    return "pickle:" + base64.b64encode(pickle.dumps(obj)).decode()
                except (pickle.PicklingError, TypeError, AttributeError) as e:
                    raise SerializationError(f"Cannot serialize object: {e}") from e

    @staticmethod
    def loads(data: str, allow_pickle: bool = False) -> Any:
        """
        Deserialize string with format detection.

        Args:
            data: Serialized string (with "safe:" or "pickle:" prefix)
            allow_pickle: If False (default), reject pickle data (strict safe mode).
                         If True, accept both safe and pickle formats.

        Returns:
            Deserialized object

        Raises:
            SerializationError: If pickle data received but allow_pickle=False
        """
        if data.startswith(SafeSerializer.SAFE_PREFIX):

View on GitHub (pinned to 30bb116109)

Solutions

1. Find the unpicklable attribute (run pickle.dumps on suspected fields individually) and remove/replace it before serializing
2. Convert the object to plain dict/list/str primitives (e.g. define to_dict() or __json_safe__ conversion) before passing it
3. For resources like files/sessions, store a serializable descriptor (path, config) instead of the live object
4. As a last resort, sanitize the object (del/None out locks, sockets) before serialization

Example fix

# before
result = {"model": my_agent.model, "session": requests.Session()}
SafeSerializer.dumps(result)  # Cannot serialize object

# after
result = {"model": str(my_agent.model), "session": None}
SafeSerializer.dumps(result)

import pickle

def is_serializable(obj) -> bool:
    try:
        pickle.dumps(obj)
        return True
    except Exception:
        return False

# before dumps(): assert is_serializable(payload) or sanitize it

def is_json_safe(v) -> bool:
    return v is None or isinstance(v, (str, int, float, bool, list, dict)) and (not isinstance(v, dict) or all(is_json_safe(x) for x in v.values())) and (not isinstance(v, list) or all(is_json_safe(x) for x in v))

from smolagents.serialization import SerializationError
try:
    SafeSerializer.dumps(payload)
except SerializationError:
    payload = sanitize(payload)  # replace live resources with descriptors
    SafeSerializer.dumps(payload)

When it happens

Trigger: Calling append_answer, model_dump_json, render_as_markdown, log_messages, send_variables, or _serialize_with_fallback with an object containing non-picklable members (open files, sockets, DB connections, threading locks, lambdas, module references) after json-safe conversion already failed.

Common situations: Saving agent logs/traces where a Tool instance or action output holds a live resource (open file, requests.Session, boto3 client); lambdas stored in tool outputs; objects with __slots__ missing __getstate__; objects referencing sys.modules internals.

Related errors

• Pickle data rejected: allow_pickle=False requires safe-only
• Falling back to insecure pickle serialization. This is a sec
• Deserializing pickle data. This is a security risk if the da
• Unknown model class '{model_info['class']}'. Supported model
• Cannot safely serialize object of type {type(obj).__name__}

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/cb8232be20a29238. Report an issue: GitHub.