siyuan-note/siyuan · error · Error

--remote requires a URL

Error message

--remote requires a URL

What it means

normalizeRemoteKernelOrigin parses the value passed to the --remote CLI switch. It throws this when the switch is present but its value is empty/missing, because a remote kernel connection cannot proceed without a URL.

Source

Thrown at app/electron/remoteKernel.js:15

const crypto = require("node:crypto");

// 解析命令行参数时保留值中的等号，避免 URL 查询参数被截断。
const getArgFrom = (args, name) => {
    const prefix = name + "=";
    const arg = args.find((item) => item === name || item.startsWith(prefix));
    if (!arg) {
        return;
    }
    return arg === name ? "" : arg.slice(prefix.length);
};

const normalizeRemoteKernelOrigin = (value) => {
    if (!value) {
        throw new Error("--remote requires a URL");
    }
    const url = new URL(value);
    if (url.username || url.password) {
        throw new Error("--remote does not accept credentials in the URL");
    }
    if (url.pathname !== "/" || url.search || url.hash || value.includes("?") || value.includes("#")) {
        throw new Error("--remote only accepts an origin without a path, query, or fragment");
    }
    if (url.protocol !== "https:") {
        throw new Error("--remote requires HTTPS");
    }
    return url.origin;
};

const insecureCertificateSwitchNames = Object.freeze([
    "allow-insecure-localhost",
    "ignore-certificate-errors",
    "ignore-certificate-errors-spki-list",

View on GitHub (pinned to 8641553a1f)

Solutions

1. Pass the full origin URL: --remote https://host:port
2. Check your shortcut/launcher config — ensure the URL survived as a separate argument after --remote
3. Quote the URL if your shell treats characters like ? or # specially
4. Omit --remote entirely to start in local mode

Example fix

// before
//   SiYuan --remote
// after
//   SiYuan --remote "https://myhost:6806"

// In your launcher script, fail fast before spawning Electron:
// [ -n "$REMOTE_URL" ] || { echo "REMOTE_URL required"; exit 1; }
// exec siyuan --remote "$REMOTE_URL"

try {
  const origin = normalizeRemoteKernelOrigin(args.remote);
} catch (e) {
  if (e.message === "--remote requires a URL") {
    // print usage: --remote https://host:port
  }
}

When it happens

Trigger: Launching the Electron app with --remote and no argument, or --remote= with an empty value; the preceding argument-parsing helper returns "" when the arg is exactly the switch name.

Common situations: Copy-pasting a shortcut/desktop launcher where the URL after --remote was lost; shell quoting issues swallowing the URL; forgetting the value entirely when editing the command line.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --remote does not accept credentials in the URL
• --remote only accepts an origin without a path, query, or fr
• --remote requires HTTPS
• --old is required
• --new is required

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/c239fb19734ef4a9. Report an issue: GitHub.