invoke-ai/InvokeAI · error

Parent directory references not allowed in subfolder path

Error message

Parent directory references not allowed in subfolder path

What it means

_validate_subfolder rejects any '/'-separated subfolder containing a '..' segment, because '..' would escape the video files base directory on disk. This guard runs before any path is joined (get_path and __get_sidecar_path). It prevents directory-traversal writes/reads outside the outputs root.

Source

Thrown at invokeai/app/services/video_files/video_files_disk.py:216

        graph = sidecar.get("invokeai_graph")
        return graph if isinstance(graph, str) else None

    def validate_path(self, path: Union[str, Path]) -> bool:
        path = path if isinstance(path, Path) else Path(path)
        return path.exists()

    @staticmethod
    def _validate_subfolder(subfolder: str) -> None:
        """Validates a subfolder path to prevent directory traversal."""
        if not subfolder:
            return
        if "\\" in subfolder:
            raise ValueError("Backslashes not allowed in subfolder path")
        if subfolder.startswith("/"):
            raise ValueError("Absolute paths not allowed in subfolder path")
        for part in subfolder.split("/"):
            if part == "..":
                raise ValueError("Parent directory references not allowed in subfolder path")
            if part == "":
                raise ValueError("Empty path segments not allowed in subfolder path")

    def __get_sidecar_path(self, video_name: str, video_subfolder: str = "") -> Path:
        sidecar_name = Path(video_name).stem + ".json"
        if video_subfolder:
            self._validate_subfolder(video_subfolder)
            sidecar_path = self.__sidecars_folder / video_subfolder / sidecar_name
        else:
            sidecar_path = self.__sidecars_folder / sidecar_name
        resolved_base = self.__sidecars_folder.resolve()
        resolved_sidecar_path = sidecar_path.resolve()
        if not resolved_sidecar_path.is_relative_to(resolved_base):
            raise ValueError("Sidecar path outside outputs folder, potential directory traversal detected")
        return resolved_sidecar_path

    def __read_sidecar(self, video_name: str, video_subfolder: str = "") -> Optional[dict]:
        path = self.__get_sidecar_path(video_name, video_subfolder=video_subfolder)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Remove '..' components from the subfolder before calling the API; compute the desired path relative to the base folder
2. Normalize user input: strip or resolve '..' and validate against an allowlist of folders
3. Use pathlib and check Path(subfolder) resolves inside the base dir before passing it

Example fix

// before
get_path(name, subfolder="../shared")
// after
subfolder = "shared"  # or posixpath.normpath(raw).strip("./") validated to be relative
get_path(name, subfolder=subfolder)

def is_safe_subfolder(sub: str) -> bool:
    parts = sub.split("/") if sub else []
    return bool(parts) and all(p not in ("", ".", "..") for p in parts) and "\\" not in sub and not sub.startswith("/")

def valid_subfolder(sub: str) -> str | None:
    return sub if is_safe_subfolder(sub) else None

try:
    path = service.get_path(video_name, subfolder=sub)
except ValueError as e:
    if "subfolder" in str(e):
        path = service.get_path(video_name, subfolder="")  # fall back to root
    else:
        raise

When it happens

Trigger: Calling get_path(video_name, subfolder=...) or any sidecar operation (save, stage_delete, read) with a subfolder containing '..' segments, e.g. '../shared', 'a/../../b'.

Common situations: Client-supplied subfolder strings passed through unvalidated from an API request or workflow node; path building with os.path.join-style relative navigation on Windows/Unix; attempts to store videos outside the outputs folder.

Related errors

• Image path outside outputs folder, potential directory trave
• Sidecar path outside outputs folder, potential directory tra
• only relative download paths accepted
• Cannot derive a safe filename for {url} from '{file_name}'
• Invalid image name, potential directory traversal detected

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/eeb7683a780fe55c. Report an issue: GitHub.