{"record":{"id":"c1561cc3ca2f1e58","repo":"jackwener/OpenCLI","slug":"no-items-match-query-on-archive-org","errorCode":null,"errorMessage":"No items match \"${query}\" on archive.org.","messagePattern":"No items match \"(.+?)\" on archive\\.org\\.","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"warning","filePath":"clis/archive/search.js","lineNumber":90,"sourceCode":"        } 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        }\n\n        return docs.slice(0, limit).map((d, i) => {\n            const id = String(d.identifier ?? '');\n            if (!IDENTIFIER_RE.test(id)) {\n                throw new CommandExecutionError('archive search returned malformed payload: result row is missing a stable identifier');\n            }\n            const downloads = Number(d.downloads ?? 0);\n            if (!Number.isFinite(downloads)) {\n                throw new CommandExecutionError(`archive search returned malformed payload for \"${id}\": downloads must be numeric`);\n            }\n            const creator = Array.isArray(d.creator) ? d.creator.join(', ') : String(d.creator ?? '');\n            return {\n                rank: i + 1,\n                identifier: id,\n                title: String(d.title ?? ''),\n                creator,\n                date: d.date ? String(d.date).slice(0, 10) : '',","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/archive/search.js#L72-L108","documentation":"EmptyResultError thrown by `opencli archive search` when the archive.org advancedsearch API responds successfully but returns zero hits in response.docs. This is not a failure of the API call itself; the query parsed and executed, it simply matched nothing. The library converts an empty result set into a typed error so callers can distinguish 'no data' from 'broken payload' or 'network failure'.","triggerScenarios":"Running `opencli archive search <query>` where the HTTP request succeeds (resp.ok), the JSON parses, response.docs is an array, but that array has length 0.","commonSituations":"Misspelled search terms; over-restrictive query syntax (e.g. quoted phrases or field filters like mediatype: that match nothing); searching for identifiers/items that have been removed from archive.org; typos in metadata fields used in the query.","solutions":["Broaden the search query: remove quoted phrases, field filters, or extra keywords and retry.","Check spelling of the query terms and any field:value filters.","Verify the item still exists by browsing https://archive.org directly for the same terms.","If the empty result is expected in your workflow, catch EmptyResultError explicitly and treat it as a normal 'no rows' outcome."],"exampleFix":"// before\nopencli archive search 'collection:missingcollection AND title:\"exact phrase\"'\n// after\nopencli archive search 'collection:missingcollection'   # broaden, then refine","handlingStrategy":"try-catch","validationCode":"// Pre-check the same query against the advancedsearch API before relying on results\nconst api = `https://archive.org/advancedsearch.php?q=${encodeURIComponent(query)}&fl[]=identifier&rows=1&output=json`;\nconst data = await (await fetch(api)).json();\nconst hasHits = Array.isArray(data?.response?.docs) && data.response.docs.length > 0;\nif (!hasHits) console.warn('query will return no archive.org items');","typeGuard":"function hasDocs(data) {\n  return Array.isArray(data?.response?.docs) && data.response.docs.length > 0;\n}","tryCatchPattern":"try {\n  const rows = await run(['archive', 'search', query]);\n} catch (e) {\n  if (e instanceof EmptyResultError || /No items match/.test(e.message)) {\n    return []; // treat empty as a normal result\n  }\n  throw e;\n}","preventionTips":["Test queries interactively on archive.org before scripting them.","Start broad, then add field filters incrementally.","Explicitly handle empty-result errors as a valid outcome in pipelines."],"tags":["empty-results","search","archive-org","user-input"],"backgroundTag":"empty-result-set","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}