{"record":{"id":"d8ad320dce16a4f7","repo":"n8n-io/n8n","slug":"invalid-instance-url","errorCode":null,"errorMessage":"Invalid instance URL.","messagePattern":"Invalid instance URL\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@n8n/local-gateway/src/main/connect-origin.ts","lineNumber":12,"sourceCode":"import { isOriginAllowed } from '@n8n/computer-use/config';\n\n/**\n * Throws if the normalized instance URL's origin is not allowed by the configured patterns.\n * Call before constructing GatewayClient (deep link / IPC connect).\n */\nexport function assertConnectOriginAllowed(url: string, allowedOriginPatterns: string[]): void {\n\tlet origin: string;\n\ttry {\n\t\torigin = new URL(url.replace(/\\/$/, '')).origin;\n\t} catch {\n\t\tthrow new Error('Invalid instance URL.');\n\t}\n\tif (!isOriginAllowed(origin, allowedOriginPatterns)) {\n\t\tthrow new Error(\n\t\t\t'This instance URL is not in your allowed origins list. Open Settings and add its origin, or use a deeplink from your trusted n8n.',\n\t\t);\n\t}\n}\n","sourceCodeStart":1,"sourceCodeEnd":20,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/local-gateway/src/main/connect-origin.ts#L1-L20","documentation":"Thrown by assertConnectOriginAllowed when `new URL(url)` raises — the supplied instance URL is not parseable as a URL (after trimming a trailing slash). This runs before any network call, so it guards the deep-link / IPC connect path against malformed input. The check exists in the local gateway main process.","triggerScenarios":"Calling assertConnectOriginAllowed(url, patterns) where url is empty, missing a protocol (e.g. 'example.com'), contains invalid URL characters, or is not a string that new URL() can construct from. Triggered when a deep link or IPC connect payload carries a malformed URL field.","commonSituations":"Deep link was hand-edited or copy-pasted with the protocol stripped; an IPC message from a renderer with a missing/empty url field; a URL with spaces or non-ASCII characters that wasn't encoded; passing a bare hostname without https://.","solutions":["Ensure the URL includes a protocol: 'https://instance.example.com' not 'instance.example.com'.","Validate and encode the URL before opening the deep link.","If building the deep link programmatically, construct it with `new URL(...).toString()` on the origin side so it is always well-formed."],"exampleFix":"// before\nassertConnectOriginAllowed(userInput, allowed);\n\n// after — validate/normalize first\nfunction safeAssert(url: string, allowed: string[]) {\n  const normalized = /^https?:\\/\\//.test(url) ? url : `https://${url}`;\n  assertConnectOriginAllowed(normalized, allowed);\n}","handlingStrategy":"validation","validationCode":"function isValidInstanceUrl(url: string): boolean {\n  try {\n    // mirror the internal normalization\n    new URL(url.replace(/\\/$/, ''));\n    return true;\n  } catch {\n    return false;\n  }\n}","typeGuard":"function isParseableUrl(url: string): boolean {\n  try { new URL(url); return true; } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Construct deep-link URLs with `new URL(...).toString()` so they are always valid.","Validate the URL field in IPC payloads before they reach assertConnectOriginAllowed.","Always include the protocol (https://) when accepting user-entered instance URLs."],"tags":["local-gateway","url-validation","deeplink","validation"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}