jackwener/OpenCLI · error · CommandExecutionError

archive search returned malformed payload: result row is mis

Error message

archive search returned malformed payload: result row is missing a stable identifier

What it means

CommandExecutionError thrown during result mapping in `opencli archive search` when a row in response.docs has an identifier that is missing or fails IDENTIFIER_RE, the library's pattern for a stable archive.org identifier. The library treats every row as required to carry a usable identifier because downstream commands key off it; a row without one means the payload shape is not what was expected.

Source

Thrown at clis/archive/search.js:96

        let data;
        try {
            data = await resp.json();
        } catch (error) {
            throw new CommandExecutionError(`archive search returned malformed JSON: ${error?.message || error}`);
        }

        const docs = data?.response?.docs;
        if (!Array.isArray(docs)) {
            throw new CommandExecutionError('archive search returned malformed payload: response.docs must be an array');
        }
        if (docs.length === 0) {
            throw new EmptyResultError('archive search', `No items match "${query}" on archive.org.`);
        }

        return docs.slice(0, limit).map((d, i) => {
            const id = String(d.identifier ?? '');
            if (!IDENTIFIER_RE.test(id)) {
                throw new CommandExecutionError('archive search returned malformed payload: result row is missing a stable identifier');
            }
            const downloads = Number(d.downloads ?? 0);
            if (!Number.isFinite(downloads)) {
                throw new CommandExecutionError(`archive search returned malformed payload for "${id}": downloads must be numeric`);
            }
            const creator = Array.isArray(d.creator) ? d.creator.join(', ') : String(d.creator ?? '');
            return {
                rank: i + 1,
                identifier: id,
                title: String(d.title ?? ''),
                creator,
                date: d.date ? String(d.date).slice(0, 10) : '',
                mediatype: String(d.mediatype ?? ''),
                downloads,
                url: id ? `https://archive.org/details/${id}` : '',
            };
        });
    },

View on GitHub (pinned to 49907e53dc)

Solutions

Inspect the raw API response with the same query against https://archive.org/advancedsearch.php to see which row lacks a valid identifier.
Simplify or correct the query — malformed queries can return rows with missing identifier fields.
Report/retry later if archive.org is returning degraded payloads (transient server-side issue).
If you control the query programmatically, validate the response.docs shape yourself before mapping and skip rows without identifiers.

Defensive patterns

Strategy: validation

Validate before calling

// Validate rows before mapping, mirroring IDENTIFIER_RE expectations
const IDENTIFIER_RE = /^[\w.:-]+$/; // adjust to the library's pattern
const bad = docs.filter(d => !IDENTIFIER_RE.test(String(d.identifier ?? '')));
if (bad.length) console.warn(`skipping ${bad.length} rows without a stable identifier`);

Type guard

function hasStableIdentifier(row) {
  return typeof row?.identifier === 'string' && row.identifier.length > 0;
}

Try / catch

try {
  const rows = await run(['archive', 'search', query]);
} catch (e) {
  if (/missing a stable identifier/.test(e.message)) {
    // retry with a simplified query or surface a data-quality warning
    return retryWithSimplifiedQuery(query);
  }
  throw e;
}

Prevention

Avoid exotic query syntax that produces non-item rows.
Spot-check the raw advancedsearch.php JSON for new queries.
Pin/report library versions when archive.org schema changes.

When it happens

Trigger: The archive.org search API returns docs whose rows lack an `identifier` field (or contain one that is empty/does not match the identifier regex), typically when the query syntax triggers a non-standard response shape.

Common situations: archive.org returning odd rows for malformed or edge-case queries; API schema drift where field names change; querying with syntax that returns metadata-only documents instead of items; intermediaries/proxies altering the response.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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