jackwener/OpenCLI · error · ArgumentError

weread-official: api_name is required

Error message

weread-official: api_name is required

What it means

buildGatewayBody validates that api_name is a non-empty string before assembling the gateway request body. The WeRead gateway routes on api_name, so a missing/invalid value makes the request meaningless. The function throws ArgumentError to fail fast instead of sending a malformed request the gateway would silently mishandle.

Source

Thrown at clis/weread-official/utils.js:54

export function getApiKey() {
    const key = String(process.env.WEREAD_API_KEY ?? '').trim();
    if (!key) {
        throw new AuthRequiredError(
            WEREAD_DOMAIN,
            'WEREAD_API_KEY is not set. Export it with `export WEREAD_API_KEY=<wrk-...>`.',
        );
    }
    return key;
}

/**
 * Build the gateway request body. Business params are flattened next to
 * `api_name` and `skill_version` — never wrapped in a `params` / `data` /
 * `body` object (the gateway silently drops them and returns page 1).
 */
export function buildGatewayBody(apiName, params = {}) {
    if (!apiName || typeof apiName !== 'string') {
        throw new ArgumentError('weread-official: api_name is required');
    }
    const body = { api_name: apiName, skill_version: SKILL_VERSION };
    for (const [key, value] of Object.entries(params ?? {})) {
        if (value === undefined || value === null || value === '') continue;
        body[key] = value;
    }
    return body;
}

/**
 * POST to the agent gateway. Returns the parsed JSON payload on success.
 * Maps every documented failure mode to a typed CliError:
 *   - missing env key            → AuthRequiredError
 *   - HTTP non-2xx               → CommandExecutionError
 *   - network timeout            → TimeoutError
 *   - response includes upgrade_info → CommandExecutionError (with version hint)
 *   - errcode in AUTH_ERRCODES   → AuthRequiredError (Bearer key likely revoked)
 *   - errcode != 0               → CommandExecutionError

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass the exact gateway api_name string (e.g. 'book.search') as the first argument to buildGatewayBody.
2. Check the calling helper to ensure it forwards its apiName parameter instead of an undefined variable.
3. Coerce or validate the api name at the command-handler layer before reaching the gateway helpers.
4. Log the apiName value just before the call to confirm it is a non-empty string.

Example fix

// before
buildGatewayBody(opts.api, { query });
// after
if (typeof opts.api !== 'string' || !opts.api) throw new Error('api_name required');
buildGatewayBody(opts.api, { query });

if (typeof apiName !== 'string' || !apiName.trim()) throw new Error('api_name must be a non-empty string before calling buildGatewayBody');

const isApiName = (v) => typeof v === 'string' && v.trim().length > 0;

try {
  const body = buildGatewayBody(apiName, params);
} catch (e) {
  if (e.name === 'ArgumentError') {
    console.error(`Bad api_name: ${JSON.stringify(apiName)} — supply the gateway endpoint string`);
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling buildGatewayBody(null/undefined/''/non-string) directly, or indirectly via callGateway or the tasks/payload/bookmarks/reviews helpers when the API name constant was not passed through (e.g. a typo'd variable or undefined argument from an upstream command handler).

Common situations: Refactoring a CLI command and dropping the apiName argument; wiring a new subcommand that forgets to pass the endpoint name; JavaScript callers passing a number or an object instead of the endpoint string.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• <train-no> must not be empty
• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty
• --seat-types must contain only 12306 seat letters/digits (A-

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