{"record":{"id":"cd71cb334b4716ad","repo":"jackwener/OpenCLI","slug":"archive-search-request-failed-error-message","errorCode":null,"errorMessage":"archive search request failed: ${error?.message || error}","messagePattern":"archive search request failed: (.+?)","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/archive/search.js","lineNumber":73,"sourceCode":"        const url = new URL('https://archive.org/advancedsearch.php');\n        url.searchParams.set('q', fullQuery);\n        url.searchParams.set('output', 'json');\n        url.searchParams.set('rows', String(limit));\n        url.searchParams.set('sort[]', `${sort} desc`);\n        for (const fl of ['identifier', 'title', 'creator', 'date', 'mediatype', 'downloads']) {\n            url.searchParams.append('fl[]', fl);\n        }\n\n        let resp;\n        try {\n            resp = await fetch(url, {\n                headers: {\n                    'Accept': 'application/json',\n                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',\n                },\n            });\n        } catch (error) {\n            throw new CommandExecutionError(`archive search request failed: ${error?.message || error}`);\n        }\n        if (!resp.ok) {\n            throw new CommandExecutionError(`archive search failed: HTTP ${resp.status}`);\n        }\n        let data;\n        try {\n            data = await resp.json();\n        } catch (error) {\n            throw new CommandExecutionError(`archive search returned malformed JSON: ${error?.message || error}`);\n        }\n\n        const docs = data?.response?.docs;\n        if (!Array.isArray(docs)) {\n            throw new CommandExecutionError('archive search returned malformed payload: response.docs must be an array');\n        }\n        if (docs.length === 0) {\n            throw new EmptyResultError('archive search', `No items match \"${query}\" on archive.org.`);\n        }","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/archive/search.js#L55-L91","documentation":"This CommandExecutionError wraps any network-level failure of the fetch to archive.org's advancedsearch endpoint during `archive search`. It fires when fetch itself rejects (DNS failure, connection refused/reset, TLS error, timeout, abort) — as opposed to a non-2xx HTTP status, which produces a separate 'archive search failed: HTTP <status>' error. The original error message is interpolated into the message.","triggerScenarios":"Calling `opencli archive search ...` while offline or with DNS failures; a proxy/firewall blocking archive.org; TLS interception breaking the handshake; connection reset or socket timeout mid-request.","commonSituations":"Corporate networks requiring a proxy that is not configured (HTTPS_PROXY); VPN drops mid-command; archive.org outage or rate-limiting at the TCP level; IPv6 misresolution in containers.","solutions":["Check basic connectivity (`curl -I https://archive.org`) and DNS resolution","Configure proxy environment variables (HTTPS_PROXY/HTTPS_PROXY) if behind a corporate proxy","Retry after a short backoff — transient network blips and archive.org incidents resolve themselves","Inspect the interpolated cause in the message (e.g. 'getaddrinfo ENOTFOUND') and fix the specific network issue it names"],"exampleFix":"// before\nconst rows = await run(['archive', 'search', 'jazz']);\n// after\nlet rows;\ntry {\n    rows = await run(['archive', 'search', 'jazz']);\n} catch (err) {\n    if (/request failed/.test(String(err?.message))) {\n        rows = await run(['archive', 'search', 'jazz']); // retry once after transient network failure\n    } else {\n        throw err;\n    }\n}","handlingStrategy":"retry","validationCode":"// probe connectivity before batch runs\nconst ok = await fetch('https://archive.org/', { method: 'HEAD' }).then(r => r.ok).catch(() => false);\nif (!ok) throw new Error('archive.org unreachable; check network/proxy');","typeGuard":"null","tryCatchPattern":"try {\n    rows = await run(['archive', 'search', query]);\n} catch (err) {\n    if (err instanceof CommandExecutionError && err.message.includes('request failed')) {\n        await new Promise(r => setTimeout(r, 1000));\n        rows = await run(['archive', 'search', query]); // single retry for transient network errors\n    } else { throw err; }\n}","preventionTips":["Set HTTPS_PROXY correctly in corporate environments","Add timeout/retry with exponential backoff around CLI invocations","Probe connectivity once before batch jobs","Log the interpolated cause (DNS vs TLS vs reset) to target fixes"],"tags":["network","fetch","archive-org","cli"],"backgroundTag":"network-request-failed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}