ellite/Wallos · error · InvalidArgumentException

Invalid "period" parameter.

Error message

Invalid "period" parameter.

What it means

TOTP::getPeriod() reads the 'period' parameter and validates it is a positive integer before returning it. If the parameter is missing, not an int, or <= 0, the TOTP cannot compute timecodes, so this InvalidArgumentException is thrown.

Solutions

1. Set the period explicitly: $totp->setParameter('period', 30) before use
2. Ensure the value is a real int (cast strings: (int)$config['period'])
3. If parsing a URI, confirm the otpauth URI has a numeric period > 0 in the query string

Example fix

// before
$totp->setParameter('period', '30');
$totp->verify($code); // may hit invalid period
// after
$totp->setParameter('period', (int) $config['period']);

if (!isset($params['period']) || !is_int($params['period']) || $params['period'] <= 0) {
    $totp->setParameter('period', 30);
}

function hasValidPeriod($totp): bool {
    $v = $totp->getParameters()['period'] ?? null;
    return is_int($v) && $v > 0;
}

try {
    $period = $totp->getPeriod();
} catch (\InvalidArgumentException $e) {
    $totp->setParameter('period', 30);
    $period = $totp->getPeriod();
}

When it happens

Trigger: Calling getPeriod() (or expiresIn/verify/getProvisioningUri/timecode which call it) on a TOTP whose 'period' was never set or was set to a non-int/zero value, e.g. via setParameter('period', '30') with a string, or through a partially constructed object.

Common situations: Loading a provisioning URI whose query lacks a valid period; constructing TOTP manually and forgetting setParameter('period', 30); config value coming as a numeric string from env/INI which passed the map but stored oddly, or was bypassed entirely.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Counter must be at least 0.
• Invalid "algorithm" parameter.
• Unsupported " " OTP type
• Invalid "counter" parameter.
• The counter must be at least 0.

AI-assisted analysis of ellite/Wallos@52820e87ca (2026-09-13). Data as JSON: /api/errors/2254a7f067a6eba8. Report an issue: GitHub.

Appendix: source

Thrown at libs/OTPHP/TOTP.php:73

    {
        $totp = new self($secret, $clock);
        $totp->setPeriod(self::DEFAULT_PERIOD);
        $totp->setDigest(self::DEFAULT_DIGEST);
        $totp->setDigits(self::DEFAULT_DIGITS);
        $totp->setEpoch(self::DEFAULT_EPOCH);

        return $totp;
    }

    public static function generate(?ClockInterface $clock = null): self
    {
        return self::createFromSecret(self::generateSecret(), $clock);
    }

    public function getPeriod(): int
    {
        $value = $this->getParameter('period');
        (is_int($value) && $value > 0) || throw new InvalidArgumentException('Invalid "period" parameter.');

        return $value;
    }

    public function getEpoch(): int
    {
        $value = $this->getParameter('epoch');
        (is_int($value) && $value >= 0) || throw new InvalidArgumentException('Invalid "epoch" parameter.');

        return $value;
    }

    public function expiresIn(): int
    {
        $period = $this->getPeriod();

        return $period - ($this->clock->now()->getTimestamp() % $this->getPeriod());
    }

View on GitHub (pinned to 52820e87ca)