microsoft/autogen · error · ValueError

Failed to write records to '{self.session_file_path}': {e}

Error message

Failed to write records to '{self.session_file_path}': {e}

What it means

Raised in 'record' mode when the recorder cannot persist captured records to the session JSON file. The original exception (permissions, missing directory, disk full, serialization failure) is chained, and its message is embedded in the ValueError.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/experimental/task_centric_memory/utils/chat_completion_client_recorder.py:220

    def finalize(self) -> None:
        """
        In record mode, saves the accumulated records to disk.
        In replay mode, makes sure all the records were checked.
        """
        self.logger.enter_function()
        if self.mode == "record":
            try:
                # Create the directory if it doesn't exist.
                os.makedirs(os.path.dirname(self.session_file_path), exist_ok=True)
                # Write the records to disk.
                with open(self.session_file_path, "w") as f:
                    json.dump(self.records, f, indent=2)
                    self.logger.info("\nRecorded session was saved to: " + self.session_file_path)
            except Exception as e:
                error_str = f"Failed to write records to '{self.session_file_path}': {e}"
                self.logger.error(error_str)
                raise ValueError(error_str) from e
        elif self.mode == "replay":
            if self._num_checked_records < len(self.records):
                error_str = f"\nEarly termination. Only {self._num_checked_records} of the {len(self.records)} recorded turns were checked."
                self.logger.error(error_str)
                raise ValueError(error_str)
            self.logger.info("\nRecorded session was fully replayed and checked.")
        self.logger.leave_function()

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Check the chained exception message ({e}) to identify the underlying OS or serialization error.
  2. Verify the directory portion of session_file_path exists and is writable, or choose a writable location (os.makedirs already attempts creation but can fail on permissions).
  3. Free disk space or fix quota limits if the write failed with ENOSPC.
  4. If json.dump failed on non-serializable content, ensure recorded messages contain only JSON-serializable types before capture.

Example fix

# before
session_file_path = "/opt/readonly/sessions/run.json"
# after
session_file_path = os.path.join(tempfile.gettempdir(), "sessions", "run.json")
Defensive patterns

Strategy: try-catch

Validate before calling

import os
parent = os.path.dirname(session_file_path)
os.makedirs(parent, exist_ok=True)
assert os.access(parent, os.W_OK), f"session directory not writable: {parent}"

Try / catch

try:
    await recorder.close()  # or the save routine
except ValueError as e:
    if "Failed to write records" in str(e):
        # e.__cause__ holds the OSError; retry to a temp location or surface it
        fallback = os.path.join(tempfile.gettempdir(), os.path.basename(session_file_path))
        recorder.session_file_path = fallback
    else:
        raise

Prevention

When it happens

Trigger: Calling the save/close routine in record mode when the session directory is unwritable, the disk is full, os.makedirs fails, or json.dump hits non-serializable objects in the recorded data.

Common situations: Read-only filesystems or containers; session_file_path pointing into a nonexistent, protected, or colliding path; records containing objects json cannot serialize (e.g. custom types leaked into messages).

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/99303db29aa053c9. Report an issue: GitHub.