langfuse/langfuse · error · OutboundUrlValidationError

invalid-encoding

invalid-encoding

Error message

Invalid URL encoding

What it means

assertValidUrlEncoding runs decodeURIComponent on the URL string purely to verify it is valid percent-encoding; malformed sequences like '%zz' or a trailing lone '%' throw invalid-encoding. The decoded value is deliberately not used, to avoid parser-differential attacks between validation and fetch.

Source

Thrown at packages/shared/src/server/outbound-url/validation.ts:195

  if (isIPBlocked(ip, whitelist.ips, whitelist.ip_ranges)) {
    logger.warn(
      `${logContext} validation blocked resolved IP address: ${ip} for hostname: ${hostname}`,
    );
    throw new OutboundUrlValidationError(
      "blocked-ip",
      "Blocked IP address detected",
    );
  }
}

function assertValidUrlEncoding(urlString: string): void {
  // This intentionally checks encoding validity only. Do not parse or validate
  // the decoded result: decoding the whole URL can turn encoded data into URL
  // delimiters and make validation inspect a different hostname than fetch.
  try {
    decodeURIComponent(urlString);
  } catch {
    throw new OutboundUrlValidationError(
      "invalid-encoding",
      "Invalid URL encoding",
    );
  }
}

View on GitHub (pinned to 59d92c7cf3)

Solutions

1. Encode URL components properly: use encodeURIComponent on values interpolated into the URL.
2. Fix or remove malformed % sequences in the configured URL.
3. Test with decodeURIComponent(url) in a scratch script before saving the config.

Example fix

// before
const url = `https://host/?q=${q}`; // q = "50% off"
// after
const url = `https://host/?q=${encodeURIComponent(q)}`;

function isValidEncoding(u: string): boolean { try { decodeURIComponent(u); return true; } catch { return false; } }

null

catch (e) { if (e.code === "invalid-encoding") reencodeComponentsAndRetry(); else throw e; }

When it happens

Trigger: Passing a URL containing invalid percent-escapes, e.g. 'https://host/path%zz', 'https://host/50%', or double-broken encodings, to any outbound URL validation entry point.

Common situations: String concatenation that forgets encodeURIComponent (raw '%' in query values); user input with stray percent signs; partially-encoded URLs from logs or configs.

Related errors

• invalid-syntax
• View '${viewName}' is not supported in version '${version}'.
• Invalid entity dimension: ${field}. Must be one of ${Object.
• Invalid dimension ${dimension.field}. Must be one of ${Objec
• Field '${filter.column}' cannot be used as a filter.

AI-assisted analysis of langfuse/langfuse@59d92c7cf3 (2026-08-27). Data as JSON: /api/errors/17f503a07a99321b. Report an issue: GitHub.