paperclipai/paperclip · error

Enter the Hermes API base URL.

Error message

Enter the Hermes API base URL.

What it means

For the hermes_gateway adapter type, preparedConfig() parses the gateway URL with new URL() and requires an http: or https: protocol. If the trimmed gatewayUrl is empty, malformed, or uses another scheme, the parse/validation throws internally and the catch re-throws "Enter the Hermes API base URL." as the user-facing validation error.

Source

Thrown at ui/src/components/new-agent/NewAgentSetup.tsx:396

      !/^https:\/\/github\.com\/[^/]+\/[^/]+/.test(repository.trim())
    )
      throw new Error("Enter a GitHub repository URL.");
    if (
      ["cursor_cloud", "hermes_gateway"].includes(adapterType) &&
      !apiKey.trim() &&
      !selectedBinding
    )
      throw new Error(
        adapterType === "cursor_cloud"
          ? "Enter a Cursor API key."
          : `Enter ${envKey} or select an organization secret.`,
      );
    if (adapterType === "hermes_gateway") {
      try {
        const url = new URL(gatewayUrl.trim());
        if (!["https:", "http:"].includes(url.protocol)) throw new Error();
      } catch {
        throw new Error("Enter the Hermes API base URL.");
      }
    }
    if (usingKimiApi && !kimiModel.trim())
      throw new Error("Enter the Kimi API model name.");
    return buildConfig(nextConnection);
  }
  function pendingCredentials(nextConnection = connection) {
    return {
      ...nextConnection?.credentials,
      ...(hasCredentialField && apiKey.trim()
        ? { [envKey]: apiKey.trim() }
        : {}),
    };
  }

  async function runTest(nextConnection = connection): Promise<boolean> {
    if (!ready) return false;
    const run = ++generation.current;

View on GitHub (pinned to 01ad858492)

Solutions

1. Enter the full gateway base URL including the scheme, e.g. https://hermes.example.com.
2. Prepend https:// if you entered a bare hostname.
3. Use only http: or https: schemes — other protocols are rejected.
4. Verify no stray whitespace/characters break URL parsing.

Example fix

// before
gatewayUrl: "hermes.internal:8443"

// after
gatewayUrl: "https://hermes.internal:8443"

let gatewayOk = false;
try {
  const u = new URL(gatewayUrl.trim());
  gatewayOk = ["https:", "http:"].includes(u.protocol);
} catch { gatewayOk = false; }
if (adapterType === "hermes_gateway" && !gatewayOk)
  showError("Enter the Hermes API base URL.");

const isValidHttpUrl = (s: string): boolean => {
  try {
    return ["https:", "http:"].includes(new URL(s.trim()).protocol);
  } catch { return false; }
};

try {
  const cfg = preparedConfig();
  submit(cfg);
} catch (e) {
  if (e instanceof Error && e.message.includes("Hermes API base URL")) {
    setGatewayFieldError("Use a full http(s) URL, e.g. https://hermes.example.com");
  } else throw e;
}

When it happens

Trigger: Submitting setup with adapterType "hermes_gateway" and gatewayUrl empty, "localhost:8080" (no scheme), "ftp://...", or any string that new URL() cannot parse.

Common situations: Leaving the Hermes gateway field blank; entering a host without https://; pasting a URL with a typo or trailing invalid characters; using a non-HTTP scheme.

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

• Enter a GitHub repository URL.
• Enter the Kimi API model name.
• Invalid configured Paperclip API origin
• Choose or enter a model in provider/model format.
• Enter a Cursor API key.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/96b0a39de84abfc9. Report an issue: GitHub.