What causes "index must be a positive integer" in jackwener/OpenCLI?

Pass a whole-number index >= 1 (1 = the most recent post), e.g. `--index 3` for the third newest post.

index must be a positive integer

Error message

index must be a positive integer

What it means

The `save` command accepts a 1-based `--index` argument identifying which post of a user's feed to bookmark. Inside the browser pipeline, the raw args.index value is interpolated directly and decremented to a 0-based `idx`; if the resulting value is not an integer or is negative, the script throws this error before any network calls. It is a guard against non-numeric or sub-1 (e.g. 0 or negative) post positions, since the count parameter in the feed API request would otherwise be invalid.

Source

Thrown at clis/instagram/save.js:23

    access: 'write',
    description: 'Save (bookmark) an Instagram post',
    domain: 'www.instagram.com',
    args: [
        {
            name: 'username',
            required: true,
            positional: true,
            help: 'Username of the post author',
        },
        { name: 'index', type: 'int', default: 1, help: 'Post index (1 = most recent)' },
    ],
    columns: ['status', 'user', 'post'],
    pipeline: [
        { navigate: 'https://www.instagram.com' },
        { evaluate: `(async () => {
  const username = \${{ args.username | json }};
  const idx = \${{ args.index }} - 1;
  if (!Number.isInteger(idx) || idx < 0) throw new Error('index must be a positive integer');
  const headers = { 'X-IG-App-ID': '936619743392459' };
  const opts = { credentials: 'include', headers };
  async function readInstagramJson(response, label) {
    try {
      return await response.json();
    } catch {
      throw new Error(label + ' returned invalid JSON');
    }
  }
  function getPostFromFeed(feed, label) {
    if (!feed || typeof feed !== 'object' || !Array.isArray(feed.items)) {
      throw new Error(label + ' returned malformed items payload');
    }
    if (idx >= feed.items.length) throw new Error('Post index ' + (idx + 1) + ' not found');
    const post = feed.items[idx];
    const pkRaw = post?.pk ?? post?.id;
    const pk = typeof pkRaw === 'number' ? String(pkRaw) : (typeof pkRaw === 'string' ? pkRaw.trim() : '');
    if (!/^\\d+$/.test(pk)) throw new Error(label + ' returned malformed post row');

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a whole-number index >= 1 (1 = the most recent post), e.g. `--index 3` for the third newest post.
If you meant the first post, omit `--index` entirely — it defaults to 1.
Check the calling script/wrapper for empty or non-numeric values being forwarded as the index and coerce/validate them before invoking the command.

Example fix

// before (0-based intent)
instagram save someuser --index 0

// after (1-based: 1 = most recent)
instagram save someuser --index 1

Defensive patterns

Strategy: validation

Validate before calling

const idx = Number(args.index);
if (!Number.isInteger(idx) || idx < 1) {
  throw new Error(`--index must be a whole number >= 1 (1 = most recent post), got: ${args.index}`);
}

Type guard

function isValidIndex(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 1;
}

Try / catch

try {
  await run(['instagram', 'save', username, '--index', String(i)]);
} catch (e) {
  if (String(e.message).includes('index must be a positive integer')) {
    console.error('Use a 1-based index (1 = most recent post)');
  }
  throw e;
}

Prevention

Always treat --index as 1-based: 1 is the most recent post, never pass 0.
Coerce and validate user-supplied index in wrapper scripts before invoking the command.
Omit --index to accept the default of 1 when you want the newest post.

When it happens

Trigger: Running the instagram save command with an `--index` value that, after the `args.index - 1` subtraction, is not a non-negative integer: passing 0 or a negative number, passing a non-integer like 1.5 (when the arg is not coerced to int), or passing a value that interpolates as NaN/undefined (e.g. missing or malformed argument).

Common situations: A developer thinks the index is 0-based and passes `--index 0` to target the first (most recent) post; a wrapper script forwards an empty or non-numeric variable as the index; an automation supplies a float from a computation; or the arg type 'int' default fails and `undefined - 1` becomes 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 jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/e55db9d8d9acb4b3. Report an issue: GitHub.