{"record":{"id":"2e80900f0349b775","repo":"jackwener/OpenCLI","slug":"archive-snapshots-returned-malformed-cdx-payload-2e8090","errorCode":null,"errorMessage":"archive snapshots returned malformed CDX payload: top-level payload must be an array","messagePattern":"archive snapshots returned malformed CDX payload: top-level payload must be an array","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/archive/snapshots.js","lineNumber":90,"sourceCode":"                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',\n                },\n            });\n        } catch (error) {\n            throw new CommandExecutionError(`archive snapshots request failed: ${error?.message || error}`);\n        }\n        if (!resp.ok) {\n            throw new CommandExecutionError(`archive snapshots failed: HTTP ${resp.status}`);\n        }\n        let data;\n        try {\n            data = await resp.json();\n        } catch (error) {\n            throw new CommandExecutionError(`archive snapshots returned malformed JSON: ${error?.message || error}`);\n        }\n\n        // CDX returns an array of arrays; the first row is the header.\n        if (!Array.isArray(data)) {\n            throw new CommandExecutionError('archive snapshots returned malformed CDX payload: top-level payload must be an array');\n        }\n        if (data.length < 2) {\n            throw new EmptyResultError('archive snapshots', `No Wayback snapshots for \"${target}\".`);\n        }\n        const [header, ...rows] = data;\n        if (!Array.isArray(header)) {\n            throw new CommandExecutionError('archive snapshots returned malformed CDX payload: header row must be an array');\n        }\n        const cols = {};\n        header.forEach((name, i) => { cols[name] = i; });\n        const timestampCol = requireCdxColumn(cols, 'timestamp');\n        const originalCol = requireCdxColumn(cols, 'original');\n        const statusCol = requireCdxColumn(cols, 'statuscode');\n        const mimetypeCol = requireCdxColumn(cols, 'mimetype');\n\n        return rows.slice(0, limit).map(row => {\n            if (!Array.isArray(row)) {\n                throw new CommandExecutionError('archive snapshots returned malformed CDX payload: snapshot row must be an array');","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/archive/snapshots.js#L72-L108","documentation":"After successfully parsing the CDX response as JSON, the library verifies the CDX contract: a JSON array of arrays whose first row is the column header. This error is thrown when the parsed body is valid JSON but not a top-level array (e.g. an object with an error field, or a different shape entirely).","triggerScenarios":"The CDX API returned valid JSON that is not an array — for example `{\"error\": ...}` for blocked/invalid requests that still return HTTP 200, a changed API response shape, or an intermediary (proxy/gateway) returning its own JSON error object with status 200.","commonSituations":"Wayback CDX deprecations or API changes altering the response envelope; transparent proxies returning JSON-formatted error pages; calling an unofficial CDX mirror with a different response shape; URL query strings causing the API to return an error object instead of rows.","solutions":["Print/inspect the raw response body (`curl 'http://web.archive.org/cdx/search/cdx?url=YOUR_URL&output=json&limit=2'`) to see the actual payload shape.","Check that the target URL argument is a plain URL/path — overly long or odd query strings can push CDX into an error-object response.","Verify the CDX API is healthy (status.archive.org) and whether the response contract changed; update the opencli package if a newer version adapts to it.","Retry later if the API is temporarily serving error objects."],"exampleFix":"// before: ambiguous URL with query string\nawait exec('opencli archive snapshots \"example.com/page?utm=x&a=1\"');\n// after: strip tracking query params so CDX returns normal rows\nawait exec('opencli archive snapshots example.com/page');","handlingStrategy":"type-guard","validationCode":"// Validate the expected CDX envelope after receiving raw JSON elsewhere\nfunction looksLikeCdx(v) { return Array.isArray(v); }","typeGuard":"function isCdxPayload(v) {\n  return Array.isArray(v) && v.length >= 1 && Array.isArray(v[0]);\n}","tryCatchPattern":"try {\n  await exec('opencli archive snapshots example.com');\n} catch (e) {\n  if (String(e.message).includes('top-level payload must be an array')) {\n    console.error('CDX response shape changed or an error object was returned; inspect raw payload');\n  } else throw e;\n}","preventionTips":["Keep the target URL simple (strip tracking query params)","Watch archive.org API announcements for CDX contract changes","Keep the opencli package updated","Inspect raw CDX output when upgrading tooling"],"tags":["json","schema","cdx-api","wayback-machine"],"backgroundTag":"unexpected-response-schema","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}