microsoft/autogen · error · ValueError

Working directory (cwd) '{cwd}' is not valid. It must be wit

Error message

Working directory (cwd) '{cwd}' is not valid. It must be within the base path.

What it means

Thrown by MarkdownFileBrowser's constructor when an explicitly passed cwd fails _validate_path(), i.e. the resolved working directory does not fall inside the configured base_path. The browser sandboxes all file access to base_path, so any cwd outside it is rejected at init. Note this only fires when YOU supply cwd; when cwd is None the class falls back to os.getcwd() (if valid) or base_path.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/file_surfer/_markdown_file_browser.py:56

        self._markdown_converter = MarkItDown()
        self._base_path = None if base_path is None else os.path.realpath(base_path)
        self._page_content: str = ""
        self._find_on_page_query: Union[str, None] = None
        self._find_on_page_last_result: Union[int, None] = None  # Location of the last result

        # Set the working directory
        if cwd is None:
            if self._validate_path(os.getcwd()):
                # Use the current working directory if it's in the base path
                cwd = os.path.realpath(os.getcwd())
            elif self._base_path is not None:
                # Otherwise, use the base path
                cwd = os.path.realpath(self._base_path)
            else:
                raise ValueError("No valid working directory (cwd) provided.")
        elif not self._validate_path(cwd):
            # A cwd was provided, but it is not valid
            raise ValueError(f"Working directory (cwd) '{cwd}' is not valid. It must be within the base path.")

        # Populate the history with the current working directory
        self.set_path(os.path.realpath(cwd))

    @property
    def path(self) -> str:
        """Return the path of the current page."""
        assert len(self.history) > 0
        return self.history[-1][0]

    def _validate_path(self, path: str) -> bool:
        """Validates the path to ensure it is within the base path.

        Arguments:
            path: The path to validate.
        Returns:
            True if the path is valid, False otherwise.
        """

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass a cwd that is inside base_path, e.g. cwd=base_path itself or a subdirectory of it.
Omit cwd entirely so the constructor falls back to base_path when os.getcwd() is not valid.
If the intended working directory is correct, widen base_path so it is an ancestor of cwd (e.g. a common parent directory).
Check for symlinks: the validation uses realpath, so a cwd that looks inside base_path but resolves outside will fail; use os.path.realpath on both before constructing.

Example fix

# before
browser = MarkdownFileBrowser(
    path_uri="file:///home/user/docs/readme.md",
    base_path="/data",
    cwd="/home/user/docs",
)

# after
browser = MarkdownFileBrowser(
    path_uri="file:///data/docs/readme.md",
    base_path="/data",
    cwd="/data/docs",
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def valid_cwd(base_path: str, cwd: str) -> bool:
    base = os.path.realpath(base_path)
    candidate = os.path.realpath(cwd)
    return candidate == base or candidate.startswith(base + os.sep)

Prevention

Always compute cwd from base_path (e.g. cwd=base_path) instead of an independent absolute path.
Remember validation uses realpath — resolve symlinks on both paths before comparing.
In notebooks/containers, explicitly pass cwd rather than relying on os.getcwd().

When it happens

Trigger: Constructing MarkdownFileBrowser(path_uri=..., base_path='/data') with cwd='/home/user' (or any path outside /data), including cases where symlinks resolve outside base_path since _validate_path works on real paths.

Common situations: Running an agent in a Docker container or notebook where os.getcwd() differs from the intended document root; passing a relative cwd that resolves against an unexpected current directory; setting base_path to a subdirectory while forgetting to update cwd; symlinked paths escaping base_path after realpath resolution.

Related errors

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