Budibase/budibase · error · Error

Plugin must be compressed into a gzipped tarball.

Error message

Plugin must be compressed into a gzipped tarball.

What it means

Thrown when the URL is a valid HTTPS URL but its pathname does not end with '.tar.gz', so it is not recognized as a gzipped tarball plugin archive.

Source

Thrown at packages/server/src/api/controllers/plugin/url.ts:20

import {
  deleteFolderFileSystem,
  getPluginMetadata,
} from "../../../utilities/fileSystem"

function parseTarGzUrl(url: string): URL {
  let parsed: URL
  try {
    parsed = new URL(url)
  } catch {
    throw new Error("Invalid plugin URL.")
  }

  if (parsed.protocol !== "https:") {
    throw new Error("Plugin URL must use HTTPS.")
  }

  if (!parsed.pathname.endsWith(".tar.gz")) {
    throw new Error("Plugin must be compressed into a gzipped tarball.")
  }

  return parsed
}

export async function urlUpload(url: string, name = "", headers = {}) {
  parseTarGzUrl(url)

  const path = await downloadUnzipTarball(url, name, headers, {
    followRedirects: false,
  })
  try {
    return await getPluginMetadata(path)
  } catch (err) {
    deleteFolderFileSystem(path)
    throw err
  }
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Provide a direct link to a .tar.gz archive
2. For GitHub, use the release asset or https://github.com/<org>/<repo>/archive/refs/tags/<tag>.tar.gz
3. Strip query strings, or host the file at a path ending in .tar.gz

Example fix

// before
await urlUpload('https://github.com/org/repo/releases/latest')
// after
await urlUpload('https://github.com/org/repo/releases/download/v1.0.0/plugin-1.0.0.tar.gz')

const u = new URL(url)
if (!u.pathname.endsWith('.tar.gz')) throw new Error('URL must point directly at a .tar.gz archive (no query strings)')

function isTarGzUrl(url: string): boolean {
  try { return new URL(url).pathname.endsWith('.tar.gz') } catch { return false }
}

try {
  await urlUpload(url)
} catch (err) {
  if (err.message === 'Plugin must be compressed into a gzipped tarball.') {
    // point the URL at the actual .tar.gz asset
  }
}

When it happens

Trigger: urlUpload called with URLs pointing to .zip files, bare package pages, URLs with query strings after the filename, or extensionless download endpoints.

Common situations: Pointing at a GitHub repo page instead of a release .tar.gz asset; using .zip archives from a CI artifact; URLs like https://host/plugin.tar.gz?token=x (fails the endsWith check).

Related errors

• Invalid plugin URL.
• Invalid URL.
• Only HTTP(S) URLs are allowed.
• Plugin missing .js file.
• Invalid Github URL

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/950e2257403ffeea. Report an issue: GitHub.