invoke-ai/InvokeAI · error

Image path outside outputs folder, potential directory trave

Error message

Image path outside outputs folder, potential directory traversal detected

What it means

After building the final path, get_path resolves it and confirms it stays inside the resolved base folder (outputs or thumbnails). This final containment check catches cases where the resolved path escapes the base (e.g. symlinks or remaining traversal), raising ValueError otherwise.

Source

Thrown at invokeai/app/services/image_files/image_files_disk.py:273

        # Validate the filename itself (no path separators allowed in the filename)
        basename = Path(filename).name
        if basename != filename:
            raise ValueError("Invalid image name, potential directory traversal detected")

        # Build the full path with optional subfolder
        if image_subfolder:
            self._validate_subfolder(image_subfolder)
            image_path = base_folder / image_subfolder / basename
        else:
            image_path = base_folder / basename

        # Ensure the image path is within the base folder to prevent directory traversal
        resolved_base = base_folder.resolve()
        resolved_image_path = image_path.resolve()

        if not resolved_image_path.is_relative_to(resolved_base):
            raise ValueError("Image path outside outputs folder, potential directory traversal detected")

        return resolved_image_path

    @staticmethod
    def _validate_subfolder(subfolder: str) -> None:
        """Validates a subfolder path to prevent directory traversal while allowing controlled subdirectories."""
        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")
        parts = subfolder.split("/")
        for part in parts:
            if part == "..":
                raise ValueError("Parent directory references not allowed in subfolder path")
            if part == "":
                raise ValueError("Empty path segments not allowed in subfolder path")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Remove symlinks inside the outputs/thumbnails folders or point them inside the base folder
2. Recreate the outputs folder with real directories (no symlinked subfolders)
3. Ensure the configured output folder path itself is a real, resolved directory

Example fix

// before
ln -s /external/data outputs/movies
// after
mkdir outputs/movies  # real directory inside the outputs folder

from pathlib import Path
base = Path('outputs').resolve()
def path_is_contained(name: str, subfolder: str = '') -> bool:
    p = (base / subfolder / name).resolve()
    return p.is_relative_to(base)
assert path_is_contained('img.png', 'sub')

def resolves_inside(name: str, base: Path) -> bool:
    return (base / name).resolve().is_relative_to(base.resolve())

try:
    path = service.get_path(image_name, image_subfolder=subfolder)
except ValueError as e:
    logger.error('Path containment failed: %s', e)
    raise HTTPException(400, 'Path escapes outputs folder') from e

When it happens

Trigger: Calling get/save/stage_delete where the resolved path of base_folder + subfolder + basename is outside the base folder — e.g. a symlinked subfolder pointing elsewhere, or validation bypassed via unusual path forms.

Common situations: Output folder itself containing symlinks to external directories; mounting or relocating the outputs dir while retaining symlinks; OS-level path aliases (short names, case tricks).

Related errors

• Parent directory references not allowed in subfolder path
• 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/f1c1704890949b72. Report an issue: GitHub.