briannesbitt/Carbon · error · NotAPeriodException

Argument 1 passed to {$class}::{$method}() must be an instan

Error message

Argument 1 passed to {$class}::{$method}() must be an instance of DatePeriod or {$class}, instance of {$given} given.

What it means

CarbonPeriod::instance(mixed $period) (src/Carbon/CarbonPeriod.php:358-390) only accepts an existing CarbonPeriod (copied) or a native DatePeriod (its start/end/interval/recurrences are read out). The parameter is deliberately typed mixed, so any other value (a Carbon date, CarbonInterval, array, string, null) cannot be converted and produces NotAPeriodException instead of a PHP TypeError.

Source

Thrown at src/Carbon/CarbonPeriod.php:386

                $period->getDateInterval(),
                $period->getOptions(),
            );
        }

        if ($period instanceof DatePeriod) {
            return new static(
                $period->start,
                $period->end ?: ($period->recurrences - 1),
                $period->interval,
                $period->include_start_date ? 0 : static::EXCLUDE_START_DATE,
            );
        }

        $class = static::class;
        $type = \gettype($period);
        $chunks = explode('::', __METHOD__);

        throw new NotAPeriodException(
            'Argument 1 passed to '.$class.'::'.end($chunks).'() '.
            'must be an instance of DatePeriod or '.$class.', '.
            ($type === 'object' ? 'instance of '.\get_class($period) : $type).' given.',
        );
    }

    /**
     * Create a new instance.
     */
    public static function create(...$params): static
    {
        return static::createFromArray($params);
    }

    /**
     * Create a new instance from an array of parameters.
     */
    public static function createFromArray(array $params): static

View on GitHub (pinned to b13f05955d)

Solutions

1. Branch by type: use instance() only for DatePeriod/CarbonPeriod; build with CarbonPeriod::create($start, $end) or CarbonPeriod::create($start, 'P1D', $n) otherwise
2. Use CarbonPeriod::make($var): it calls instance() and falls back to create() when that throws (src/Carbon/CarbonPeriod.php:346-352)
3. If you have the pieces, wrap them in a native period first: new DatePeriod($start, $interval, $end)

Example fix

// before
$period = CarbonPeriod::instance($input); // explodes on Carbon/array/string

// after
$period = CarbonPeriod::make($input); // instance() for periods, create() fallback

// or explicit
$period = ($input instanceof DatePeriod || $input instanceof CarbonPeriod)
    ? CarbonPeriod::instance($input)
    : CarbonPeriod::create($input);

/** @psalm-assert DatePeriod|CarbonPeriod $value */
function assertPeriodLike(mixed $value): void
{
    if (!$value instanceof CarbonPeriod && !$value instanceof DatePeriod) {
        throw new InvalidArgumentException(
            'Expected CarbonPeriod|DatePeriod, got '.get_debug_type($value)
        );
    }
}

assertPeriodLike($input);
$period = CarbonPeriod::instance($input);

try {
    $period = CarbonPeriod::instance($input);
} catch (\Carbon\Exceptions\NotAPeriodException $e) {
    $period = CarbonPeriod::create($input); // or reject the input
}

When it happens

Trigger: CarbonPeriod::instance(Carbon::parse('2021-01-01')); CarbonPeriod::instance($someCarbonInterval); CarbonPeriod::instance(['2021-01-01', '2021-12-31']); CarbonPeriod::instance('2021-01-01') — even a valid date string is rejected here, only period objects are accepted.

Common situations: Code that receives 'maybe a period' from a DTO/user input and calls instance() unconditionally; refactoring create() calls into instance(); passing a DatePeriod look-alike from another library (e.g. league/period) that does not extend DatePeriod.

Related errors

• Invalid ISO 8601 specification: {$iso}.
• $anchorDay parameter must not be set for $mode OverflowMode:
• You must specify $end or $recurrences but not both
• Invalid constructor parameters.
• $name

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