What causes "Clock only understands numbers, 'mm:ss' and 'hh:mm:ss'" in microsoft/playwright?

Pass a number of milliseconds, or an 'mm:ss' / 'hh:mm:ss' string.

microsoft/playwright · error · Error

Clock only understands numbers, 'mm:ss' and 'hh:mm:ss'

Error message

Clock only understands numbers, 'mm:ss' and 'hh:mm:ss'

What it means

Thrown by parseLength in clock.ts:133. The synthetic clock's length parser accepts only numbers, or strings matching mm:ss / hh:mm:ss; anything else (more than three colon segments, non-digit characters, units like '1h', malformed strings) is rejected.

Source

Thrown at packages/playwright-core/src/server/clock.ts:133

 * Parse strings like '01:10:00' (meaning 1 hour, 10 minutes, 0 seconds) into
 * number of milliseconds. This is used to support human-readable strings passed
 * to clock.tick()
 */
function parseTicks(value: number | string): number {
  if (typeof value === 'number')
    return value;
  if (!value)
    return 0;
  const str = value;

  const strings = str.split(':');
  const l = strings.length;
  let i = l;
  let ms = 0;
  let parsed;

  if (l > 3 || !/^(\d\d:){0,2}\d\d?$/.test(str)) {
    throw new Error(
        `Clock only understands numbers, 'mm:ss' and 'hh:mm:ss'`,
    );
  }

  while (i--) {
    parsed = parseInt(strings[i], 10);
    if (parsed >= 60)
      throw new Error(`Invalid time ${str}`);
    ms += parsed * Math.pow(60, l - i - 1);
  }

  return ms * 1000;
}

function parseTime(epoch: string | number | undefined): number {
  if (!epoch)
    return 0;
  const parsed = new Date(epoch);

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Pass a number of milliseconds, or an 'mm:ss' / 'hh:mm:ss' string.
Convert durations up front: 90*60*1000 for 90 minutes.
For absolute install times use Date.now() or an ISO string parsed by setFixedTime.

Example fix

// before
await page.clock.advance('1h30m');
// after
await page.clock.advance(90 * 60 * 1000);

Defensive patterns

Strategy: validation

Validate before calling

// Accept ms, 'mm:ss', or 'hh:mm:ss' only.
function toClockLength(v: number | string): number | string {
  if (typeof v === 'number') return v;
  if (/^(\d\d:){0,2}\d\d?$/.test(v)) return v;
  throw new Error(`Clock length must be a number or mm:ss / hh:mm:ss, got: ${v}`);
}
await page.clock.advance(toClockLength(input));

Type guard

function isClockLength(v: unknown): v is number | string {
  if (typeof v === 'number') return true;
  if (typeof v !== 'string') return false;
  return /^(\d\d:){0,2}\d\d?$/.test(v);
}

Prevention

Pass milliseconds as a plain number to avoid format ambiguity.
Avoid unit strings ('1h', '90s') from date libraries — convert first.
If you must use a string, restrict to mm:ss or hh:mm:ss with two-digit fields.

When it happens

Trigger: clock.advance('1h30m'); clock.advance('1:2:3:4'); clock.setFixedTime('noon'); clock.advance('90sec').

Common situations: Mixing unit strings from libraries (moment/dayjs durations); passing human-readable times; passing ISO 8601 durations.

Related errors

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/2163f86b333ffdad. Report an issue: GitHub.