calesthio/OpenMontage · error · TimeoutError

TokenHub task {task_id} did not finish within {timeout_secon

Error message

TokenHub task {task_id} did not finish within {timeout_seconds}s

What it means

TimeoutError raised when the TokenHub task does not reach a terminal status (completed/failed) within the caller-supplied timeout_seconds window. The poller loops with poll_interval until the deadline; non-terminal statuses simply continue, so a stuck or slow task eventually exhausts the budget.

Source

Thrown at tools/graphics/hunyuan_image.py:521

                    raise RuntimeError(
                        f"TokenHub task {task_id} completed but no data[].url: {data}"
                    )
                return urls

            if status == "failed":
                error_info = data.get("error") or {}
                error_msg = error_info.get("message", "unknown error")
                raise RuntimeError(
                    f"TokenHub task {task_id} failed: {error_msg}"
                )

            # queued / running / in_progress — continue polling
            if status not in ("queued", "running", "in_progress"):
                raise RuntimeError(
                    f"TokenHub task {task_id} returned unknown status: {status}"
                )

        raise TimeoutError(
            f"TokenHub task {task_id} did not finish within {timeout_seconds}s"
        )

    # ------------------------------------------------------------------
    # Error handling helpers
    # ------------------------------------------------------------------

    @staticmethod
    def _safe_error(exc: Exception) -> str:
        """Redact secret values from exception messages."""
        msg = str(exc)
        for var in ("TENCENT_TOKENHUB_API_KEY",):
            val = os.environ.get(var, "")
            if val:
                msg = msg.replace(val, "[redacted]")
        return msg

    @staticmethod

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Increase the timeout_seconds input for the call (e.g. 600+ for multi-image requests)
Check TokenHub status/announcements for congestion before long retry loops
Reduce requested image count or resolution so the task finishes faster
Note the task may still complete server-side; polling the same task_id again (if you captured it) can recover the result without re-spending

Example fix

// before
inputs = {"prompt": "...", "timeout_seconds": 120}
// after
inputs = {"prompt": "...", "timeout_seconds": 600, "poll_interval": 3}

Defensive patterns

Strategy: retry

Validate before calling

inputs["timeout_seconds"] = max(int(inputs.get("timeout_seconds", 0)), 600)

Try / catch

try:
    urls = client._poll_task(task_id, timeout_seconds=600, ...)
except TimeoutError:
    # task may still finish server-side; re-poll the same task_id if you captured it

Prevention

Scale timeout_seconds with requested image count and resolution
Persist task_id at submit time so timeouts are recoverable, not lossy
Avoid tight poll_interval values that add API load without speeding the task

When it happens

Trigger: Long Hunyuan generations (high resolution, many images) exceeding a tight timeout_seconds; TokenHub queue congestion; a task wedged in 'running' due to an upstream incident.

Common situations: Default timeout too short for batch-size=n requests; peak-hour queue backlog; timeout value copied from a faster model's invocation.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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