cube-js/cube · error · Error

Unable to detect archive format from its contents. Supported

Error message

Unable to detect archive format from its contents. Supported formats are gzip (.tar.gz/.tgz), tar and zip.

What it means

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.

Source

Thrown at packages/cubejs-backend-shared/src/http-utils.ts:170

  // end-of-central-directory record that an empty archive consists of.
  if (startsWith(0x50, 0x4b)) {
    await extractZip(archivePath, { dir: path.resolve(cwd) });
    return;
  }

  // Uncompressed tar: "ustar" at offset 257.
  if (bytesRead >= 262 && header.subarray(257, 262).toString('latin1') === 'ustar') {
    await tar.x({ file: archivePath, cwd, ...tarOptions });
    return;
  }

  if (startsWith(0x42, 0x5a, 0x68)) {
    throw new Error(
      'Unsupported archive format: bzip2. Supported formats are gzip (.tar.gz/.tgz), tar and zip.'
    );
  }

  throw new Error(
    'Unable to detect archive format from its contents. Supported formats are gzip (.tar.gz/.tgz), tar and zip.'
  );
}

type DownloadAndExtractFile = {
  showProgress: boolean;
  cwd: string;
  skipExtract?: boolean;
  dstFileName?: string;
};

export async function downloadAndExtractFile(url: string, { cwd, skipExtract, dstFileName }: DownloadAndExtractFile) {
  const request = new Request(url, {
    headers: new Headers({
      'Content-Type': 'application/octet-stream',
    }),
    agent: await getHttpAgentForProxySettings(),
  });

View on GitHub (pinned to 7d981676b3)

Solutions

1. Point the download URL at an artifact in .tar.gz/.tgz, .tar, or .zip format (recompress or use a mirror that provides one)
2. Pre-extract the archive yourself and use skipExtract: true in downloadAndExtractFile to just download the file without extraction
3. Verify the URL actually serves an archive (curl -sI / curl -s | file -) — an HTML error page or redirect body will fail sniffing
4. Re-download the file; a truncated download may have lost the magic-byte header

Example fix

// before
downloadAndExtractFile('https://mirror.example.com/driver.tar.xz', { cwd, showProgress: true });
// after
downloadAndExtractFile('https://mirror.example.com/driver.tar.gz', { cwd, showProgress: true });

const header = Buffer.alloc(4);
const fd = await fs.promises.open(archivePath, 'r');
await fd.read(header, 0, 4, 0);
await fd.close();
const isGzip = header[0] === 0x1f && header[1] === 0x8b;
const isZip = header[0] === 0x50 && header[1] === 0x4b;
if (!isGzip && !isZip) throw new Error(`${url} does not serve a supported archive (.tar.gz/.tgz, tar, zip)`);

function isSupportedArchive(header: Buffer): boolean {
  return (header[0] === 0x1f && header[1] === 0x8b) || // gzip
    (header[0] === 0x50 && header[1] === 0x4b) ||      // zip
    header.subarray(0, 262).toString('latin1').slice(257, 262) === 'ustar';
}

try {
  await downloadAndExtractFile(url, { cwd, showProgress: true });
} catch (e) {
  if (e.message.includes('Unable to detect archive format')) {
    console.error(`Downloaded artifact from ${url} is not a supported archive; check the URL/mirror`);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• tar skipped an entry while extracting (${code}): ${message}
• tar skipped an entry (${code}): ${message}
• unexpected response ${response.statusText}
• release archive does not contain a cube binary

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/fc955bc8b597c1f6. Report an issue: GitHub.