jackwener/OpenCLI · error · ArgumentError

openalex work id is required (e.g. "W2741809807", "10.7717/p

Error message

openalex work id is required (e.g. "W2741809807", "10.7717/peerj.4375")

What it means

requireWorkRef resolves a user-supplied work identifier (W-id, DOI, or URL) and throws ArgumentError when the input is empty or whitespace-only. The message reminds callers of the accepted formats: a Work id like W2741809807 or a DOI like 10.7717/peerj.4375. Unlike requireString this is ref-specific because the resolved value is used to build an OpenAlex works path.

Source

Thrown at clis/openalex/utils.js:46

    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`openalex ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`openalex ${label} must be <= ${maxValue}`);
    }
    return n;
}

/**
 * Resolve a user-supplied work identifier to OpenAlex's canonical path
 * segment. Accepts `W…` IDs, `doi:10.…`, raw DOIs, or full
 * `https://doi.org/…` / `https://openalex.org/W…` URLs.
 */
export function requireWorkRef(value) {
    const raw = String(value ?? '').trim();
    if (!raw) {
        throw new ArgumentError('openalex work id is required (e.g. "W2741809807", "10.7717/peerj.4375")');
    }
    // 1) full openalex URL
    const oaUrl = raw.match(/^https?:\/\/(?:api\.)?openalex\.org\/(?:works\/)?([WAaSCFwIPwT]\d+)/i);
    if (oaUrl) {
        const id = oaUrl[1].toUpperCase();
        if (id[0] !== 'W') {
            throw new ArgumentError(`openalex work id "${value}" must be a Work (W…) ID, got "${id[0]}…"`);
        }
        return id;
    }
    // 2) bare W… id
    if (WORK_ID.test(raw.toUpperCase())) {
        return raw.toUpperCase();
    }
    // 3) doi:… prefix
    if (/^doi:/i.test(raw)) {
        const doi = raw.replace(/^doi:/i, '').trim();
        if (DOI_BARE.test(doi)) return `doi:${doi}`;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Supply a valid work reference: a W-id, a bare DOI, a doi.org URL, or an openalex.org URL
2. Check that the variable feeding the ref is actually set and non-empty
3. If the ref came from a prior search, verify that search returned a result before chaining

Example fix

// before
const id = process.env.WORK_ID; // unset
await work(id);
// after
const id = process.env.WORK_ID;
if (!id?.trim()) { console.error('WORK_ID must be set, e.g. W2741809807'); process.exit(1); }
await work(id);

function assertWorkRef(ref) {
  if (!String(ref ?? '').trim()) {
    throw new Error('work ref is required (W-id or DOI)');
  }
}

function hasWorkRef(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  await work(ref);
} catch (e) {
  if (e.name === 'ArgumentError' && e.message.includes('is required')) {
    console.error('Provide a W-id or DOI, e.g. W2741809807'); process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling a work-lookup command (ref/get) with an empty or whitespace-only `ref` argument — null/undefined coerce to '' via String(value ?? '').trim().

Common situations: Shell variable holding the paper ID is unset; CLI positional argument omitted; a pipeline step upstream produced an empty ID because a prior search returned nothing.

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

• openalex ${label} cannot be empty
• openalex ${label} must be a positive integer
• openalex ${label} must be <= ${maxValue}
• openalex work id "${value}" must be a Work (W…) ID, got "${i
• openalex work id "${value}" is not recognised

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