koala73/worldmonitor · error · ValidationError

Unknown scenario: ${scenarioId}

Error message

Unknown scenario: ${scenarioId}

What it means

Validation in runScenario: the trimmed scenarioId has no entry in the scenario catalog (getScenario returned nothing). The id is well-formed enough to check but unknown — a typo, a removed scenario, or a catalog drift between client and server.

Source

Thrown at server/worldmonitor/scenario/v1/run-scenario.ts:39

  let suffix = '';
  const array = new Uint8Array(8);
  crypto.getRandomValues(array);
  for (const byte of array) suffix += JOB_ID_CHARSET[byte % JOB_ID_CHARSET.length];
  return `scenario:${ts}:${suffix}`;
}

export async function runScenario(
  ctx: ServerContext,
  req: RunScenarioRequest,
): Promise<RunScenarioResponse> {
  await requirePremiumRpcAccess(ctx.request, ApiError, 'PRO subscription required');

  const scenarioId = (req.scenarioId ?? '').trim();
  if (!scenarioId) {
    throw new ValidationError([{ field: 'scenarioId', description: 'scenarioId is required' }]);
  }
  if (!getScenarioTemplate(scenarioId)) {
    throw new ValidationError([{ field: 'scenarioId', description: `Unknown scenario: ${scenarioId}` }]);
  }

  const iso2 = req.iso2 ? req.iso2.trim() : '';
  if (iso2 && !/^[A-Z]{2}$/.test(iso2)) {
    throw new ValidationError([{ field: 'iso2', description: 'iso2 must be a 2-letter uppercase country code' }]);
  }

  // Queue-depth backpressure. Raw key: worker reads it unprefixed, so we must too.
  const [depthEntry] = await runRedisPipeline([['LLEN', QUEUE_KEY]], true);
  const depth = typeof depthEntry?.result === 'number' ? depthEntry.result : 0;
  if (depth > MAX_QUEUE_DEPTH) {
    throw new ApiError(429, 'Scenario queue is at capacity, please try again later', '');
  }

  const jobId = generateJobId();
  const payload = JSON.stringify({
    jobId,
    scenarioId,

View on GitHub (pinned to eeab0a219f)

Solutions

1. Use a scenarioId from the current server-side scenario catalog
2. If the client list is stale, refresh it so only existing scenarios are offered

When it happens

Trigger: Thrown at server/worldmonitor/scenario/v1/run-scenario.ts:39 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of koala73/worldmonitor@eeab0a219f (2026-08-21). Data as JSON: /api/errors/52a49ea6b6ef4e94. Report an issue: GitHub.