What causes "Total must be at least 1" in PrefectHQ/fastmcp?

Ensure the computed total is >= 1 before calling set_total (e.g. `max(1, len(items))` or skip set_total when there is no work)

PrefectHQ/fastmcp · error · ValueError

Total must be at least 1

Error message

Total must be at least 1

What it means

The Progress dependency's set_total() validates that the reported total/target is at least 1 and raises ValueError otherwise. Progress in MCP is a counter that starts at 1-based values, so a total of 0 or negative is meaningless and would produce broken progress notifications.

Source

Thrown at fastmcp_slim/fastmcp/server/dependencies.py:1188

    ) -> None:
        pass

    @property
    def current(self) -> int | None:
        return self._current

    @property
    def total(self) -> int:
        return self._total

    @property
    def message(self) -> str | None:
        return self._message

    async def set_total(self, total: int) -> None:
        """Set the total/target value for progress tracking."""
        if total < 1:
            raise ValueError("Total must be at least 1")
        self._total = total

    async def increment(self, amount: int = 1) -> None:
        """Atomically increment the current progress value."""
        if amount < 1:
            raise ValueError("Amount must be at least 1")
        if self._current is None:
            self._current = amount
        else:
            self._current += amount

    async def set_message(self, message: str | None) -> None:
        """Update the progress status message."""
        self._message = message


class Progress(Dependency["Progress"]):
    """Progress dependency that works in both server and worker contexts.

View on GitHub (pinned to 1f02114297)

Solutions

Ensure the computed total is >= 1 before calling set_total (e.g. `max(1, len(items))` or skip set_total when there is no work)
Guard: only call set_total when you actually have items to process
If the work size is unknown upfront, avoid set_total and just use increment/report_progress

Example fix

// before
total = len(items)
await progress.set_total(total)  # ValueError when items == []
// after
if items:
    await progress.set_total(len(items))

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(total, int) or total < 1:
    raise ValueError(f'total must be a positive int, got {total!r}')
await progress.set_total(total)

Try / catch

try:
    await progress.set_total(total)
except ValueError:
    logger.warning(f'ignoring invalid progress total {total!r}')

Prevention

Clamp computed totals with max(1, n)
Skip set_total for empty workloads
Never pass floats or bools (bool is an int — True==1 passes, False==0 raises)
Default totals to len(items) only after confirming items is non-empty

When it happens

Trigger: Calling `await progress.set_total(0)` or `await progress.set_total(-5)` (or a computed total that evaluates to 0, e.g. len of an empty list) inside a tool handler.

Common situations: Computing the total from a dynamically sized collection (empty items list); initializing progress before knowing the work size; off-by-one or uninitialized counter variables.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/39515653cd723ae8. Report an issue: GitHub.