cube-js/cube · error · Error

options.timestampPrecision is required, actual: ${options.ti

Error message

options.timestampPrecision is required, actual: ${options.timestampPrecision}

What it means

timeSeries() requires options.timestampPrecision to be set (truthy); the default parameter only applies when options is omitted entirely, so passing an explicit options object without timestampPrecision (or with 0/undefined) triggers this throw. The precision controls the millisecond precision of generated range timestamps and must be explicitly confirmed.

Source

Thrown at packages/cubejs-backend-shared/src/time.ts:246

      alignedStart.clone()
        .subtract(1, 'second')
        .format(`YYYY-MM-DDTHH:mm:ss.${'9'.repeat(options.timestampPrecision)}`)
    ]);
  }

  return dates;
};

/**
 * Returns array of date ranges for a predefined granularity aligned with the start of the year as pivot point
 */
export const timeSeries = (granularity: string, dateRange: QueryDateRange, options: TimeSeriesOptions = { timestampPrecision: 3 }): QueryDateRange[] => {
  if (!TIME_SERIES[granularity]) {
    throw new Error(`Unsupported time granularity: ${granularity}`);
  }

  if (!options.timestampPrecision) {
    throw new Error(`options.timestampPrecision is required, actual: ${options.timestampPrecision}`);
  }

  checkSeriesForDateRange(`1 ${granularity}`, dateRange);

  // moment.range works with strings
  const range = moment.range(<any>dateRange[0], <any>dateRange[1]);

  return TIME_SERIES[granularity](range, options.timestampPrecision);
};

export const isPredefinedGranularity = (granularity: string): boolean => !!TIME_SERIES[granularity];

export const FROM_PARTITION_RANGE = '__FROM_PARTITION_RANGE';

export const TO_PARTITION_RANGE = '__TO_PARTITION_RANGE';

export const BUILD_RANGE_START_LOCAL = '__BUILD_RANGE_START_LOCAL';

View on GitHub (pinned to 7d981676b3)

Solutions

1. Pass { timestampPrecision: 3 } (or the precision you need) in the options object.
2. Omit the options argument entirely so the default { timestampPrecision: 3 } applies.
3. Merge defaults before calling: options = { timestampPrecision: 3, ...partialOptions }.

Example fix

// before
timeSeries('day', range, {}); // throws: timestampPrecision is required

// after
timeSeries('day', range, { timestampPrecision: 3 });

function buildTimeSeriesOptions(o: Partial<{ timestampPrecision: number }> = {}) {
  const opts = { timestampPrecision: 3, ...o };
  if (!opts.timestampPrecision) throw new Error('timestampPrecision must be set (e.g. 3 for milliseconds)');
  return opts;
}

function hasTimestampPrecision(o: unknown): o is { timestampPrecision: number } {
  return typeof o === 'object' && o !== null && typeof (o as any).timestampPrecision === 'number' && (o as any).timestampPrecision > 0;
}

try {
  return timeSeries(g, range, userOptions);
} catch (e) {
  if (/timestampPrecision is required/.test(String(e))) {
    return timeSeries(g, range, { ...userOptions, timestampPrecision: 3 });
  }
  throw e;
}

When it happens

Trigger: timeSeries('day', range, {}) or timeSeries('day', range, { timestampPrecision: undefined }) — any call supplying an options object lacking a truthy timestampPrecision.

Common situations: Spreading partial config objects ({...userOptions}) into options; building options conditionally where timestampPrecision is dropped; TypeScript callers relying on the default but then passing an empty object literal.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• The count of generated date ranges (${count}) for the reques
• Unsupported time granularity: ${granularity}
• Timezone must be a string, got ${typeof value}
• Time series queries without dateRange aren't supported
• Can't parse date: '${from}'

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/28fec0f59a6ade6e. Report an issue: GitHub.