{"record":{"id":"fc955bc8b597c1f6","repo":"cube-js/cube","slug":"unable-to-detect-archive-format-from-its-contents","errorCode":null,"errorMessage":"Unable to detect archive format from its contents. Supported formats are gzip (.tar.gz/.tgz), tar and zip.","messagePattern":"Unable to detect archive format from its contents\\. Supported formats are gzip \\(\\.tar\\.gz/\\.tgz\\), tar and zip\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cubejs-backend-shared/src/http-utils.ts","lineNumber":170,"sourceCode":"  // end-of-central-directory record that an empty archive consists of.\n  if (startsWith(0x50, 0x4b)) {\n    await extractZip(archivePath, { dir: path.resolve(cwd) });\n    return;\n  }\n\n  // Uncompressed tar: \"ustar\" at offset 257.\n  if (bytesRead >= 262 && header.subarray(257, 262).toString('latin1') === 'ustar') {\n    await tar.x({ file: archivePath, cwd, ...tarOptions });\n    return;\n  }\n\n  if (startsWith(0x42, 0x5a, 0x68)) {\n    throw new Error(\n      'Unsupported archive format: bzip2. Supported formats are gzip (.tar.gz/.tgz), tar and zip.'\n    );\n  }\n\n  throw new Error(\n    'Unable to detect archive format from its contents. Supported formats are gzip (.tar.gz/.tgz), tar and zip.'\n  );\n}\n\ntype DownloadAndExtractFile = {\n  showProgress: boolean;\n  cwd: string;\n  skipExtract?: boolean;\n  dstFileName?: string;\n};\n\nexport async function downloadAndExtractFile(url: string, { cwd, skipExtract, dstFileName }: DownloadAndExtractFile) {\n  const request = new Request(url, {\n    headers: new Headers({\n      'Content-Type': 'application/octet-stream',\n    }),\n    agent: await getHttpAgentForProxySettings(),\n  });","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-backend-shared/src/http-utils.ts#L152-L188","documentation":"extractArchive() sniffs the first bytes of a downloaded archive (magic bytes) and dispatches to tar or zip extraction. If the file matches none of the supported signatures — gzip (1f 8b), zip (PK), or ustar tar — and is not bzip2, this error is thrown because the library cannot determine how to extract the file.","triggerScenarios":"Calling downloadAndExtractFile (or extractArchive directly) with a URL that serves an unsupported compression format (e.g. zstd, xz, plain binary, 7z, or an HTML error page instead of an archive), or a truncated/corrupt file whose leading bytes no longer match any known magic signature.","commonSituations":"Configuring a custom JDBC driver or Cube Store release download URL pointing at a .tar.xz or .7z artifact; a proxy/captive portal returning an HTML error page with HTTP 200 so the saved file is HTML, not an archive; a mirror serving zstd-compressed tarballs; truncated download.","solutions":["Point the download URL at an artifact in .tar.gz/.tgz, .tar, or .zip format (recompress or use a mirror that provides one)","Pre-extract the archive yourself and use skipExtract: true in downloadAndExtractFile to just download the file without extraction","Verify the URL actually serves an archive (curl -sI / curl -s | file -) — an HTML error page or redirect body will fail sniffing","Re-download the file; a truncated download may have lost the magic-byte header"],"exampleFix":"// before\ndownloadAndExtractFile('https://mirror.example.com/driver.tar.xz', { cwd, showProgress: true });\n// after\ndownloadAndExtractFile('https://mirror.example.com/driver.tar.gz', { cwd, showProgress: true });","handlingStrategy":"validation","validationCode":"const header = Buffer.alloc(4);\nconst fd = await fs.promises.open(archivePath, 'r');\nawait fd.read(header, 0, 4, 0);\nawait fd.close();\nconst isGzip = header[0] === 0x1f && header[1] === 0x8b;\nconst isZip = header[0] === 0x50 && header[1] === 0x4b;\nif (!isGzip && !isZip) throw new Error(`${url} does not serve a supported archive (.tar.gz/.tgz, tar, zip)`);","typeGuard":"function isSupportedArchive(header: Buffer): boolean {\n  return (header[0] === 0x1f && header[1] === 0x8b) || // gzip\n    (header[0] === 0x50 && header[1] === 0x4b) ||      // zip\n    header.subarray(0, 262).toString('latin1').slice(257, 262) === 'ustar';\n}","tryCatchPattern":"try {\n  await downloadAndExtractFile(url, { cwd, showProgress: true });\n} catch (e) {\n  if (e.message.includes('Unable to detect archive format')) {\n    console.error(`Downloaded artifact from ${url} is not a supported archive; check the URL/mirror`);\n  } else throw e;\n}","preventionTips":["Verify download URLs serve .tar.gz/.tgz, .tar, or .zip artifacts (check with `curl -s <url> | file -`)","Avoid mirrors serving xz/zstd/bzip2 compressed tarballs","Use skipExtract: true when the artifact is not an archive you need unpacked","Watch for proxies returning HTML error pages with 200 status; validate the response content type"],"tags":["archive","download","unsupported-format","extraction"],"backgroundTag":"unsupported-archive-format","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}