microsoft/autogen · error · ValueError

File '{filename}' does not exist on the canvas; create it fi

Error message

File '{filename}' does not exist on the canvas; create it first.

What it means

TextCanvas is a revision-tracked file store; operations that modify or read an existing file call _ensure_file, which raises ValueError naming the missing filename. The file must be created via add_or_update_file before patching, diffing, or reading revisions of it.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/memory/canvas/_text_canvas.py:59

    # ----------------------------------------------------------------------------------

    def __init__(self) -> None:
        # For each file we keep an *ordered* list of FileRevision where the last
        # element is the most recent.  Using a list keeps the memory footprint
        # small and preserves order without any extra bookkeeping.
        self._files: Dict[str, List[FileRevision]] = {}

    # ----------------------------------------------------------------------------------
    # Internal utilities
    # ----------------------------------------------------------------------------------

    def _latest_idx(self, filename: str) -> int:
        """Return the index (not revision number) of the newest revision."""
        return len(self._files.get(filename, [])) - 1

    def _ensure_file(self, filename: str) -> None:
        if filename not in self._files:
            raise ValueError(f"File '{filename}' does not exist on the canvas; create it first.")

    # ----------------------------------------------------------------------------------
    # Revision inspection helpers
    # ----------------------------------------------------------------------------------

    def get_revision_content(self, filename: str, revision: int) -> str:  # NEW 🚀
        """Return the exact content stored in *revision*.

        If the revision does not exist an empty string is returned so that
        downstream code can handle the "not found" case without exceptions.
        """
        for rev in self._files.get(filename, []):
            if rev.revision == revision:
                return rev.content
        return ""

    def get_revision_diffs(self, filename: str) -> List[str]:  # NEW 🚀
        """Return a *chronological* list of unified‑diffs for *filename*.

View on GitHub (pinned to 027ecf0a37)

Solutions

Create the file first with canvas.add_or_update_file(filename, content) before applying patches.
Normalize filenames (strip './', lowercase if appropriate) so create and patch use the identical key.
Check existence via get_latest_content(filename) != "" or an explicit membership check before patching.

Example fix

# before
canvas.apply_patch("notes.md", patch_text)
# after
if not canvas.get_latest_content("notes.md"):
    canvas.add_or_update_file("notes.md", "")
canvas.apply_patch("notes.md", patch_text)

Defensive patterns

Strategy: validation

Validate before calling

if not canvas.get_latest_content(filename):
    canvas.add_or_update_file(filename, "")  # ensure the file exists before patching
canvas.apply_patch(filename, patch_text)

Type guard

def canvas_has_file(canvas, filename: str) -> bool:
    return canvas.get_latest_content(filename) != ""

Try / catch

try:
    canvas.apply_patch(filename, patch_text)
except ValueError as e:
    if "does not exist on the canvas" in str(e):
        canvas.add_or_update_file(filename, "")
        canvas.apply_patch(filename, patch_text)
    else:
        raise

Prevention

Normalize filenames (strip './', fix case) before any canvas call.
Always create files with add_or_update_file before patching or diffing.
When driving the canvas from LLM tool calls, validate the tool schema enforces create-before-patch.

When it happens

Trigger: Calling apply_patch, get_diff, get_revision_content-dependent mutation paths, or other revision operations on a filename never created with add_or_update_file, or after the canvas was cleared/reset.

Common situations: Agent LLM emits a patch for a file it never created first; filename mismatch (leading './', case, different path spelling) between the create call and the patch call; assuming the canvas pre-seeds files.

Related errors

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