jackwener/OpenCLI · error · CommandExecutionError

archive item returned malformed payload: files must be an ar

Error message

archive item returned malformed payload: files must be an array

What it means

This CommandExecutionError is thrown by the `archive item` command when the archive.org /metadata/<identifier> endpoint returns a JSON payload whose `files` field is not an array. The CLI normalizes metadata fields (creator, collection, description) and expects `data.files` to be an array so it can count files; anything else (missing, null, object, string) is treated as a malformed response. It indicates the remote API returned an unexpected shape rather than a caller input mistake.

Source

Thrown at clis/archive/item.js:77

        const meta = data?.metadata;
        // The metadata endpoint returns {} for missing or dark items.
        if (!meta || typeof meta !== 'object' || !meta.identifier) {
            throw new EmptyResultError('archive item', `No public metadata for "${identifier}" on archive.org.`);
        }
        const responseIdentifier = String(meta.identifier);
        if (!IDENTIFIER_RE.test(responseIdentifier)) {
            throw new CommandExecutionError('archive item returned malformed payload: metadata.identifier is not stable');
        }
        if (responseIdentifier !== identifier) {
            throw new CommandExecutionError(`archive item returned metadata for "${responseIdentifier}" instead of "${identifier}"`);
        }

        const creator = Array.isArray(meta.creator) ? meta.creator.join(', ') : String(meta.creator ?? '');
        const collection = Array.isArray(meta.collection) ? meta.collection.join(', ') : String(meta.collection ?? '');
        const description = Array.isArray(meta.description) ? meta.description.join(' ') : String(meta.description ?? '');
        if (!Array.isArray(data.files)) {
            throw new CommandExecutionError('archive item returned malformed payload: files must be an array');
        }

        return [{
            identifier: responseIdentifier,
            title: String(meta.title ?? ''),
            creator,
            date: meta.date ? String(meta.date).slice(0, 10) : '',
            mediatype: String(meta.mediatype ?? ''),
            collection,
            description,
            file_count: data.files.length,
            url: `https://archive.org/details/${responseIdentifier}`,
        }];
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Retry the command — transient archive.org partial responses often resolve on retry
2. Verify the identifier points to a concrete item (not a collection) that publicly lists files
3. Inspect the raw payload with `curl https://archive.org/metadata/<identifier>` to confirm the `files` field shape
4. If the item legitimately has no files list, treat the item as empty rather than malformed and/or catch CommandExecutionError and fall back to metadata-only output

Example fix

// before
const rows = await run(['archive', 'item', identifier]);
// after
let rows;
try {
    rows = await run(['archive', 'item', identifier]);
} catch (err) {
    if (/files must be an array/.test(String(err?.message))) {
        rows = []; // item exposes no files list; proceed with metadata only
    } else {
        throw err;
    }
}

const meta = await fetchMetadata(identifier);
if (!Array.isArray(meta?.files)) {
    console.warn(`item ${identifier} has no files array; skipping`);
}

function hasFilesArray(data) {
    return Boolean(data) && typeof data === 'object' && Array.isArray(data.files);
}

try {
    rows = await run(['archive', 'item', id]);
} catch (err) {
    if (err instanceof CommandExecutionError && err.message.includes('files must be an array')) {
        rows = []; // treat as file-less item
    } else { throw err; }
}

When it happens

Trigger: Calling `opencli archive item <identifier>` where the archive.org metadata response lacks a `files` array — e.g. the item is a collection or dark item, archive.org serves a partial/degraded metadata document, a proxy/CDN returns an HTML error page with 200, or the item schema changed.

Common situations: Fetching metadata for collection-type identifiers where `files` is absent; archive.org serving truncated responses during incidents; corporate proxies intercepting the request and returning non-JSON/odd JSON; scraping very old or unusual items whose metadata never had a files list.

Understand the failure class

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

Related errors

• archive search returned malformed payload: response.docs mus
• archive search failed: HTTP ${resp.status}
• archive search request failed: ${error?.message || error}
• archive search returned malformed JSON: ${error?.message ||
• hf spaces failed: HTTP ${resp.status}

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