Budibase/budibase · error · Error

Invalid NPM URL

Error message

Invalid NPM URL

What it means

npm plugin uploads must reference an https URL; parseNpmUrl first ensures the string is a valid URL at all. If new URL() throws (malformed URL), this error is thrown before any host checks.

Source

Thrown at packages/server/src/api/controllers/plugin/npm.ts:14

import { utils as coreUtils } from "@budibase/backend-core"
import {
  deleteFolderFileSystem,
  getPluginMetadata,
} from "../../../utilities/fileSystem"
import { join } from "path"
import { downloadUnzipTarball } from "./utils"

function parseNpmUrl(url: string): URL {
  let parsed: URL
  try {
    parsed = new URL(url)
  } catch {
    throw new Error("Invalid NPM URL")
  }

  if (parsed.protocol !== "https:") {
    throw new Error("The plugin origin must be from NPM")
  }

  return parsed
}

function isAllowedNpmHost(host: string): boolean {
  return host === "www.npmjs.com" || host === "registry.npmjs.org"
}

export async function npmUpload(url: string, name: string, headers = {}) {
  let npmTarballUrl = url
  let pluginName = name

  const parsedInput = parseNpmUrl(npmTarballUrl)

View on GitHub (pinned to a81a902e9a)

Solutions

1. Provide a full https URL, e.g. https://www.npmjs.com/package/@org/plugin or a https://registry.npmjs.org/...tgz tarball URL
2. Fix the scheme typo and ensure no leading/trailing whitespace
3. Convert a bare package name into https://www.npmjs.com/package/<name>

Example fix

// before
await installPlugin({ source: 'NPM', url: '@org/my-plugin' })
// after
await installPlugin({ source: 'NPM', url: 'https://www.npmjs.com/package/@org/my-plugin' })

function isValidUrl(url: string): boolean {
  try { new URL(url); return true } catch { return false }
}
if (!isValidUrl(url.trim())) throw new Error(`Not a URL: ${url}`)

function isParseableUrl(url: string): url is string {
  try { new URL(url); return true } catch { return false }
}

try {
  await installPlugin({ source: 'NPM', url: url.trim() })
} catch (err) {
  if (err.message === 'Invalid NPM URL') {
    console.error(`'${url}' is not a URL — use https://www.npmjs.com/package/<name> or a registry tarball URL`)
  }
}

When it happens

Trigger: Calling npmUpload (plugin create with source=NPM) with a value that is not a parseable URL — missing scheme (npmjs.com/package/foo), whitespace, typo like 'https//', or an npm package name instead of a URL.

Common situations: Pasting 'npm install @org/pkg' output; supplying 'org/pkg' package name instead of a full URL; trailing spaces from copy/paste; using registry:protocol or git+ssh URLs.

Related errors

• The plugin origin must be from NPM
• Invalid URL.
• Only HTTP(S) URLs are allowed.
• Invalid Github URL
• The plugin origin must be from Github

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