jackwener/OpenCLI · error · ArgumentError

--${definition.arg} must be one of: ${Object.keys(definition

Error message

--${definition.arg} must be one of: ${Object.keys(definition.options).join(', ')}, got ${JSON.stringify(value)}

What it means

resolveSearchFilters maps each declared search filter (sort, note type, publish time, etc.) from its CLI argument value to a UI option defined in SEARCH_FILTERS. If the provided value is not a string or is not a key of definition.options, this ArgumentError is thrown listing all valid options. It is a strict allowlist check on filter argument values.

Source

Thrown at clis/xiaohongshu/search.js:340

    return result;
}
export function parseLimit(raw) {
    const parsed = Number(raw ?? 20);
    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
        throw new ArgumentError(`--limit must be an integer between 1 and 100, got ${JSON.stringify(raw)}`);
    }
    if (parsed < 1 || parsed > 100) {
        throw new ArgumentError(`--limit must be between 1 and 100, got ${parsed}`);
    }
    return parsed;
}

function resolveSearchFilters(kwargs) {
    return SEARCH_FILTERS.map((definition) => {
        const value = kwargs[definition.arg] ?? definition.defaultValue;
        const option = typeof value === 'string' ? definition.options[value] : undefined;
        if (!option) {
            throw new ArgumentError(
                `--${definition.arg} must be one of: ${Object.keys(definition.options).join(', ')}, got ${JSON.stringify(value)}`,
            );
        }
        return {
            group: definition.group,
            option,
            capability: value === definition.defaultValue
                ? ''
                : definition.arg === 'location'
                    ? 'location'
                    : definition.arg === 'scope'
                        ? 'account'
                        : '',
        };
    });
}

function buildApplySearchFiltersJs(requestedFilters) {

View on GitHub (pinned to 49907e53dc)

Solutions

Use exactly one of the options listed in the error message (they are the Object.keys of definition.options)
Check SEARCH_FILTERS in clis/xiaohongshu/search.js for the current canonical option keys after upgrading
Convert programmatic values to their string key before passing (e.g. String(value))
Trim/lowercase user input if the option keys are case-sensitive and the source may include whitespace

Example fix

// before
--sort "Most Recent"
// after
--sort "newest"   // one of the keys listed in the error

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED_SORT = ['general', 'newest', 'hottest']; // mirror SEARCH_FILTERS keys
if (!ALLOWED_SORT.includes(sortArg)) {
  throw new Error(`--sort must be one of: ${ALLOWED_SORT.join(', ')}, got ${JSON.stringify(sortArg)}`);
}

Type guard

const isFilterOption = (value, options) =>
  typeof value === 'string' && Object.prototype.hasOwnProperty.call(options, value);

Try / catch

try {
  filters = resolveSearchFilters(kwargs);
} catch (e) {
  if (e instanceof ArgumentError && e.message.startsWith('--')) {
    console.error(e.message); // message already lists valid options
    process.exitCode = 1;
  } else throw e;
}

Prevention

Copy filter option keys directly from SEARCH_FILTERS instead of guessing
Trim and normalize user input to match case-sensitive option keys
Re-check option keys after upgrading the library (keys can be renamed)
Keep a mapping layer between your app's enum values and the CLI's option keys

When it happens

Trigger: Passing an unrecognized value to a filter flag, e.g. --sort newest2 or --note-type video|image, or passing a non-string value (number, object) programmatically into kwargs for a filter argument.

Common situations: Typos in filter values, guessing option names instead of checking the allowed list in the error message, version drift where option keys were renamed in a newer release, or scripts passing booleans/numbers where strings are expected.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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