jackwener/OpenCLI · error · ArgumentError

twitter collection --page-delay must be an integer between 0

Error message

twitter collection --page-delay must be an integer between 0 and 60 seconds

What it means

normalizeCollectionPageDelaySeconds validates that --page-delay is an integer in [0, 60]; out-of-range, negative, fractional, or non-numeric values throw. This delay throttles pagination requests to stay polite to the X API; the default applies when the flag is omitted.

Source

Thrown at clis/twitter/collection.js:80

    }
    return parsed;
}

function normalizeCollectionLimit(rawLimit) {
    const limit = rawLimit ?? MAX_USER_TWEETS_LIMIT;
    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_USER_TWEETS_LIMIT) {
        throw new ArgumentError(
            `twitter collection --limit must be an integer between 1 and ${MAX_USER_TWEETS_LIMIT}`,
            'Example: opencli twitter collection @jack --until 2026-07-23T00:00:00Z --limit 250',
        );
    }
    return limit;
}

function normalizeCollectionPageDelaySeconds(rawDelay) {
    const delay = rawDelay ?? DEFAULT_USER_TWEETS_PAGE_DELAY_SECONDS;
    if (!Number.isInteger(delay) || delay < 0 || delay > 60) {
        throw new ArgumentError(
            'twitter collection --page-delay must be an integer between 0 and 60 seconds',
            'Example: opencli twitter collection @jack --until 2026-07-23T00:00:00Z --page-delay 2',
        );
    }
    return delay;
}

function unwrapTweetResult(result) {
    if (!result) return null;
    if (result.__typename === 'TweetWithVisibilityResults' && result.tweet) return result.tweet;
    return result.tweet || result;
}

function relationshipTarget(result, fallbackId = null, contextStatus = 'complete') {
    const tweet = unwrapTweetResult(result);
    const user = tweet?.core?.user_results?.result;
    const rawHandle = user?.legacy?.screen_name || user?.core?.screen_name || null;
    const authorHandle = typeof rawHandle === 'string' && normalizeTwitterScreenName(rawHandle)

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass an integer number of seconds between 0 and 60, e.g. --page-delay 2
2. Omit --page-delay to use the built-in default delay
3. Strip units in scripts: pass Math.round(seconds) as a plain integer
4. If you need >60s between pages, implement an external loop that invokes the command repeatedly

Example fix

// before
--page-delay 2s
// after
--page-delay 2

function validatePageDelay(n) {
  return Number.isInteger(n) && n >= 0 && n <= 60;
}
if (!validatePageDelay(delay)) throw new Error('--page-delay must be an integer 0-60 (seconds, no units)');

function isValidDelaySeconds(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 60;
}

try {
  await run(['opencli','twitter','collection',handle,'--page-delay',String(delay)]);
} catch (err) {
  if (String(err.message).includes('--page-delay')) {
    delay = 2; // documented default-ish safe value
  } else throw err;
}

When it happens

Trigger: opencli twitter collection --page-delay -1, --page-delay 61, --page-delay 1.5, --page-delay '2s', or scripts passing NaN/undefined-as-string values instead of an integer.

Common situations: Users assuming the flag accepts units ('2s', '500ms') or floats; wanting a longer cool-down than 60s for aggressive rate-limit avoidance; automation frameworks passing wrong types.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• twitter collection --until must be an RFC3339 timestamp
• twitter collection --limit must be an integer between 1 and
• 12306 whoami failed: ${probe.detail}
• ${label} is required
• ${label} must be a positive integer

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/04e7ba68c54521bf. Report an issue: GitHub.