jackwener/OpenCLI · error · ArgumentError

--index must be "all" or an integer from 1 to ${max}

Error message

--index must be "all" or an integer from 1 to ${max}

What it means

parseImageIndices converts the --index option (e.g. for upscaling or varying a batch) into zero-based image indices. After handling "all", any value that is not purely digits (1-N) throws "--index must be \"all\" or an integer from 1 to ${max}". This is the format check; the range check produces a different message.

Source

Thrown at clis/midjourney/utils.js:82

  try {
    const parsed = new URL(raw);
    const match = parsed.pathname.match(/^\/jobs\/([0-9a-f-]{36})\/?$/i);
    if (parsed.protocol === 'https:' && parsed.hostname === MIDJOURNEY_DOMAIN && match && UUID_RE.test(match[1])) {
      return match[1].toLowerCase();
    }
  } catch {}
  throw new ArgumentError(
    'job-id must be a Midjourney UUID or https://www.midjourney.com/jobs/<uuid> URL',
    'Example: opencli midjourney status d5664250-5f1f-4cd0-9637-2ce0153dd30a',
  );
}

export function parseImageIndices(value, batchSize = 4) {
  const max = Number.isInteger(batchSize) && batchSize > 0 ? batchSize : 4;
  const raw = String(value ?? 'all').trim().toLowerCase();
  if (!raw || raw === 'all') return Array.from({ length: max }, (_, index) => index);
  if (!/^\d+$/.test(raw)) {
    throw new ArgumentError(`--index must be "all" or an integer from 1 to ${max}`);
  }
  const userIndex = Number(raw);
  if (userIndex < 1 || userIndex > max) {
    throw new ArgumentError(`--index must be between 1 and ${max} for this job`);
  }
  return [userIndex - 1];
}

export function normalizePrompt(value) {
  const prompt = String(value ?? '').replace(/\s+/g, ' ').trim();
  if (!prompt) {
    throw new ArgumentError(
      'prompt cannot be empty',
      'Example: opencli midjourney generate "a blue ceramic teapot --ar 1:1"',
    );
  }
  return prompt;
}

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Pass a single integer between 1 and the job's batch size (default 4), or the literal word "all"
  2. Replace comma lists/ranges with a single index and run the command once per image
  3. Verify you are using 1-based indexing, not 0-based
  4. Check the job's batch size to know the valid maximum

Example fix

// before
opencli midjourney upscale <job-id> --index 1,3
// after
opencli midjourney upscale <job-id> --index 1
Defensive patterns

Strategy: validation

Validate before calling

function parseIndexInput(value, batchSize = 4) {
  const raw = String(value ?? 'all').trim().toLowerCase();
  if (!raw || raw === 'all') return 'all';
  if (!/^\d+$/.test(raw)) throw new Error(`--index must be "all" or a single integer`);
  const n = Number(raw);
  if (n < 1 || n > batchSize) throw new Error(`--index must be between 1 and ${batchSize}`);
  return n;
}

Type guard

function isIndexFormat(v) {
  const raw = String(v ?? 'all').trim().toLowerCase();
  return raw === 'all' || /^\d+$/.test(raw);
}

Try / catch

try {
  await upscale(jobId, { index: parseIndexInput(opts.index) });
} catch (err) {
  if (err.name === 'ArgumentError' && /--index/.test(err.message)) {
    console.error(err.message);
    process.exitCode = 2;
  } else throw err;
}

Prevention

When it happens

Trigger: Passing --index values like "1,2" (comma-separated), "1-4" (ranges), "first", "0", or any non-numeric string. Empty string is treated as "all" and does NOT trigger this. Note "0" passes the regex but fails the range check, producing error 2628 instead.

Common situations: Users writing comma lists or ranges as they would in other tools, quoting issues in shell scripts, or using 0-based indexing out of habit when this CLI is 1-based.

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 jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/fd7a1a2bef538421. Report an issue: GitHub.