calesthio/OpenMontage · error · ValueError

workspace_path is required for this operation

Error message

workspace_path is required for this operation

What it means

Raised by _require_workspace in the HyperFrames compose tool when inputs contain no workspace_path. Edit/render-style operations operate on an existing HyperFrames workspace directory, and the helper resolves that path via Path(raw).resolve() — with no value supplied there is nothing to operate on, so it fails fast with ValueError.

Source

Thrown at tools/video/hyperframes_compose.py:991

            },
            artifacts=[str(output_path)],
        )

    @staticmethod
    def _file_digest(path: Path) -> str:
        import hashlib

        return hashlib.sha256(path.read_bytes()).hexdigest()

    # ------------------------------------------------------------------
    # Workspace generation helpers
    # ------------------------------------------------------------------

    @staticmethod
    def _require_workspace(inputs: dict[str, Any]) -> Path:
        raw = inputs.get("workspace_path")
        if not raw:
            raise ValueError("workspace_path is required for this operation")
        return Path(raw).resolve()

    @staticmethod
    def _resolve_dimensions(
        profile_name: Optional[str], fps_in: int
    ) -> tuple[int, int, int]:
        """Resolve output dimensions from the media profile, with a safe default."""
        if profile_name:
            try:
                from lib.media_profiles import get_profile  # type: ignore
                p = get_profile(profile_name)
                return int(p.width), int(p.height), int(p.fps)
            except Exception:
                pass
        return 1920, 1080, int(fps_in)

    @staticmethod
    def _compute_total_duration(cuts: list[dict]) -> float:

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Add workspace_path pointing at the HyperFrames workspace directory (the one containing the composition).
2. If starting from scratch, use the create/init operation that accepts a project path instead of an edit operation.
3. Check for exact key name — workspace_path, not workspace or path.
4. Persist the workspace path from the creating step and thread it into subsequent edit/render calls.

Example fix

# before
{"operation": "render"}

# after
{"operation": "render", "workspace_path": "/abs/project/workspaces/promo"}

from pathlib import Path

workspace = inputs.get("workspace_path")
if not workspace:
    raise ValueError("workspace_path is required for edit/render operations")
ws = Path(workspace).expanduser().resolve()
if not ws.is_dir():
    raise FileNotFoundError(f"workspace does not exist: {ws}")
inputs["workspace_path"] = str(ws)

from pathlib import Path

def is_workspace_dir(v: object) -> bool:
    return isinstance(v, str) and len(v) > 0 and Path(v).expanduser().resolve().is_dir()

When it happens

Trigger: Invoking a hyperframes_compose operation that targets an existing workspace (edit/render/inspect) without the workspace_path key, or with it set to None/empty string.

Common situations: Assuming the tool remembers the workspace from a previous compose call (it is stateless per invocation); passing project_path or directory instead of workspace_path; key typos; workflow scripts that conditionally set the key and skip it.

Related errors

• Edit mode requires image_url/image_path or image_urls/image_
• image_list items must include image, image_url, or image_pat
• image_to_video requires image_url or image_path
• reference_to_video requires reference_image_urls or referenc
• ${res.status} ${url}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/ce20fb04520289f4. Report an issue: GitHub.