What causes "Invalid number of recurrences." in briannesbitt/Carbon?

Clamp to >= 0: max(0, $recurrences)

briannesbitt/Carbon · error · InvalidPeriodParameterException

Invalid number of recurrences.

Error message

Invalid number of recurrences.

What it means

setRecurrences() bounds how many dates a period yields. A negative count is meaningless, so anything below 0 throws InvalidPeriodParameterException (src/Carbon/CarbonPeriod.php:1346). Floats are truncated to int and INF is explicitly allowed for endless periods; null removes the limit.

Source

Thrown at src/Carbon/CarbonPeriod.php:1346

        $self->handleChangedParameters();

        return $self;
    }

    /**
     * Add a recurrences filter (set maximum number of recurrences).
     *
     * @throws InvalidArgumentException
     */
    public function setRecurrences(int|float|null $recurrences): static
    {
        if ($recurrences === null) {
            return $this->removeFilter(static::RECURRENCES_FILTER);
        }

        if ($recurrences < 0) {
            throw new InvalidPeriodParameterException('Invalid number of recurrences.');
        }

        /** @var self $self */
        $self = $this->copyIfImmutable();
        $self->carbonRecurrences = $recurrences === INF ? INF : (int) $recurrences;

        return self::addFilterOrHandleChangedParameters($self, static::RECURRENCES_FILTER);
    }

    /**
     * Change the period start date.
     *
     * @param DateTime|DateTimeInterface|string $date
     * @param bool|null                         $inclusive
     *
     * @throws InvalidPeriodDateException
     *
     * @return static

View on GitHub (pinned to b13f05955d)

Solutions

Clamp to >= 0: max(0, $recurrences)
Pass null to remove the recurrence limit entirely
Use INF for a deliberate endless period: ->setRecurrences(INF)

Example fix

// before
$period->setRecurrences($count - 1); // -1 when $count = 0

// after
$period->setRecurrences(max(0, $count - 1));

Defensive patterns

Strategy: validation

Validate before calling

if ($recurrences !== null && $recurrences < 0) {
    throw new InvalidArgumentException('Recurrences must be >= 0, got '.$recurrences);
}
$period->setRecurrences($recurrences);

Prevention

Clamp computed recurrence math with max(0, ...)
Use null to remove the bound and INF for endless periods instead of negative sentinels
Validate numeric request parameters (limit/offset/count) before they reach period APIs

When it happens

Trigger: ->setRecurrences(-1); ->setRecurrences($count - 1) when $count is 0; ->setRecurrences($page - $offset) arithmetic that can go negative; passing a '-1 means unlimited' convention from another API.

Common situations: Off-by-one math producing -1; pagination code where 'limit - offset' goes negative on the last page; user input parsed with a sign error.

Related errors

AI-assisted analysis of briannesbitt/Carbon@b13f05955d (2026-08-17). Data as JSON: /api/errors/d6995f726349e2a2. Report an issue: GitHub.