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

Ensure the amount passed is >= 1; skip the call when the computed step is 0

PrefectHQ/fastmcp · error · ValueError

Amount must be at least 1

Error message

Amount must be at least 1

What it means

Progress.increment() validates that each increment amount is a positive integer (>= 1) and raises ValueError otherwise. Increments of 0 or negative values are rejected because progress must monotonically advance toward the total.

Source

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

    @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.

    In a Docket worker, delegates to the execution's Redis-backed progress
    (observable across processes). Otherwise, uses in-memory tracking.

    The shared default instance acts as a stateless factory — ``__aenter__``
    creates a fresh ``Progress`` per invocation so concurrent tasks never

View on GitHub (pinned to 1f02114297)

Solutions

Ensure the amount passed is >= 1; skip the call when the computed step is 0
Clamp with `max(1, amount)` if a minimum step makes sense for your logic
Restructure loops so increment is only called once per unit of actual work

Example fix

// before
step = len(batch)
await progress.increment(step)  # ValueError on empty batch
// after
if batch:
    await progress.increment(len(batch))

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(amount, int) or amount < 1:
    amount = max(1, int(amount or 1))  # or skip the increment
await progress.increment(amount)

Try / catch

try:
    await progress.increment(step)
except ValueError:
    pass  # zero/negative step: no progress to report

Prevention

Guard batch loops: only increment when the batch is non-empty
Never pass 0 to signal 'no change' — just don't call increment
Initialize step-size variables before the loop
Prefer increment() with default amount=1 for per-item loops

When it happens

Trigger: Calling `await progress.increment(0)`, `await progress.increment(-1)`, or passing a computed amount (e.g. a batch size or loop step) that is 0 or negative.

Common situations: Batch loops where the final batch is empty (batch_size becomes 0); arithmetic on dynamic step sizes; passing a variable that was never initialized.

Related errors

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