siyuan-note/siyuan · error · Error

--remote requires HTTPS

Error message

--remote requires HTTPS

What it means

Remote kernel connections are restricted to HTTPS so that authentication tokens and workspace data are never sent in cleartext. normalizeRemoteKernelOrigin throws when the parsed URL's protocol is anything other than https: (e.g. http:).

Source

Thrown at app/electron/remoteKernel.js:25

    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",
    "ignore-ssl-errors",
    "ignore-ssl-errors-with-hosts",
]);
const insecureCertificateSwitches = new Set(insecureCertificateSwitchNames);
const unsafeRemoteChromiumSwitchNames = Object.freeze([
    ...insecureCertificateSwitchNames,
    "allow-running-insecure-content",
    "disable-site-isolation-for-policy",
    "disable-site-isolation-trials",
    "disable-web-security",

View on GitHub (pinned to 8641553a1f)

Solutions

1. Serve the remote kernel behind a TLS-terminating reverse proxy (nginx/Caddy) and use https://
2. Obtain a valid certificate (e.g. via Let's Encrypt) for the remote host
3. For localhost testing, use a TLS-enabled tunnel (e.g. an HTTPS dev tunnel) or check whether an insecure-certificate allow-switch (see insecureCertificateSwitchNames) covers your case
4. Do not attempt to bypass by downgrading — the scheme check is intentional

Example fix

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

const u = new URL(candidate);
if (u.protocol !== "https:") {
  throw new Error("--remote requires https:// — configure TLS on the remote host");
}

const isHttpsOrigin = (v) => { try { return new URL(v).protocol === "https:"; } catch { return false; } };

try {
  const origin = normalizeRemoteKernelOrigin(args.remote);
} catch (e) {
  if (e.message === "--remote requires HTTPS") {
    // guide user to set up a TLS reverse proxy or an HTTPS tunnel
  }
}

When it happens

Trigger: Passing --remote http://host:6806 (or any non-https scheme that new URL accepts and passes the earlier checks), so url.protocol !== "https:".

Common situations: Testing against a locally exposed kernel over plain HTTP; an old internal deployment that never used TLS; copying an http:// link from documentation; a misconfigured proxy redirecting to http.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• --remote does not accept credentials in the URL
• --remote only accepts an origin without a path, query, or fr
• --remote requires a URL
• path escapes templates dir: %s
• OAuth revocation endpoint must use HTTPS or loopback HTTP

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