What causes "Priority should be between -10000 and 10000" in cube-js/cube?

Clamp or correct the priority value to be within -10000..10000 before calling executeInQueue

Priority should be between -10000 and 10000

Error message

Priority should be between -10000 and 10000

What it means

QueryQueue validates that the priority passed to executeInQueue is a number within [-10000, 10000]. Out-of-range (or NaN) priorities would corrupt queue ordering in Redis, so the queue throws immediately after opening the connection.

Source

Thrown at packages/cubejs-query-orchestrator/src/orchestrator/QueryQueue.ts:248

        queryKey: queryDef.queryKey,
        queuePrefix: this.redisQueuePrefix,
        requestId: options.requestId,
        waitingForRequestId: queryDef.requestId
      });
      if (queryHandler === 'stream') {
        throw new Error('Streaming queries to Cube Store aren\'t supported');
      }
      const result = await this.processQuerySkipQueue(queryDef, options.queueId);
      return this.parseResult(result);
    }

    const queueConnection = await this.queueDriver.createConnection();
    let waitingContext;
    let streamWait: QueryStreamWait | null = null;

    try {
      if (!(priority >= -10000 && priority <= 10000)) {
        throw new Error('Priority should be between -10000 and 10000');
      }

      // Result here won't be fetched for a forced build query and a jobbed build
      // query (initialized by the /cubejs-system/v1/pre-aggregations/jobs
      // endpoint).
      let result = !query.forceBuild && await queueConnection.getResult(queryKey, options.externalId);
      if (result && !result.streamResult) {
        return this.parseResult(result);
      }

      const queryKeyHash = this.redisHash(queryKey);

      if (query.forceBuild) {
        const jobExists = await queueConnection.getQueryDef(queryKeyHash, null);
        if (jobExists) return null;
      }

      options.orphanedTimeout = query.orphanedTimeout;

View on GitHub (pinned to 7d981676b3)

Solutions

Clamp or correct the priority value to be within -10000..10000 before calling executeInQueue
Coerce config/env-supplied values with Number() and validate before use
Use the library's own priority constants (e.g. QUERY_PRIORITY constants) instead of ad-hoc numbers

Example fix

// before
const priority = Number(process.env.QUERY_PRIORITY); // undefined -> NaN
await queue.executeInQueue(handler, key, query, priority, options);
// after
const priority = Math.max(-10000, Math.min(10000, Number(process.env.QUERY_PRIORITY) || 0));
await queue.executeInQueue(handler, key, query, priority, options);

Defensive patterns

Strategy: validation

Validate before calling

function assertPriority(p) { const n = Number(p); if (!(n >= -10000 && n <= 10000)) throw new Error(`priority ${p} out of range`); return n; }

Type guard

function isValidPriority(p: unknown): p is number { return typeof p === 'number' && p >= -10000 && p <= 10000; }

Try / catch

try { await queue.executeInQueue(...); } catch (e) { if (e.message.startsWith('Priority should be between')) { return queue.executeInQueue(handler, key, query, 0, opts); } throw e; }

Prevention

Clamp priorities with Math.max/Math.min before submitting
Coerce config values with Number() and check for NaN
Use named priority constants instead of raw numbers

When it happens

Trigger: Calling executeInQueue / executeInQueueSkipQueue with priority < -10000, > 10000, undefined/NaN, or a non-numeric value (NaN fails the >= -10000 check).

Common situations: Hard-coded extreme priorities like 99999 in custom orchestration code; priority read from config as a string; arithmetic on an undefined variable yielding NaN.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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