mastra-ai/mastra · error

Push notification URL must use http or https: ${url.protocol

Error message

Push notification URL must use http or https: ${url.protocol}

What it means

The A2A push notification sender validates the destination URL before issuing any HTTP request. If the parsed URL's protocol is not http: or https:, resolveValidatedDestination throws this error to block unsupported schemes (e.g. file:, ftp:, ws:) that fetch may not handle safely.

Source

Thrown at packages/server/src/server/a2a/push-notification-sender.ts:82

    private readonly pushNotificationStore: InMemoryPushNotificationStore,
    private readonly options: {
      timeout?: number;
      tokenHeaderName?: string;
      fetch?: typeof fetch;
      lookup?: typeof defaultLookup;
      allowedHosts?: string[];
    } = {},
  ) {}

  getStore() {
    return this.pushNotificationStore;
  }

  private async resolveValidatedDestination(rawUrl: string) {
    const url = new URL(rawUrl);

    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
      throw new Error(`Push notification URL must use http or https: ${url.protocol}`);
    }

    const hostname = url.hostname.toLowerCase();
    if (this.options.allowedHosts && !this.options.allowedHosts.includes(hostname)) {
      throw new Error(`Push notification host is not allowed: ${hostname}`);
    }

    if (isDisallowedHostname(hostname)) {
      throw new Error(`Push notification URL must not target local or internal hosts: ${hostname}`);
    }

    if (isDisallowedIpAddress(hostname)) {
      throw new Error(`Push notification URL must not target local or private IPs: ${hostname}`);
    }

    const resolvedAddresses =
      isIP(hostname) === 0
        ? await (this.options.lookup ?? defaultLookup)(hostname, { all: true, verbatim: true })

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fix the push notification URL to use https:// (or http:// for non-production) scheme
2. Validate the URL scheme on your side before registering the push notification config
3. If the value comes from env/config, print the raw value and check for typos or missing slashes
4. Use HTTPS in production; some deployments reject plain http

Example fix

// before
url: 'ftp://hooks.example.com/a2a/push'
// after
url: 'https://hooks.example.com/a2a/push'

function assertHttpUrl(raw: string) {
  const u = new URL(raw);
  if (u.protocol !== 'https:' && u.protocol !== 'http:') {
    throw new Error(`Push URL must be http(s), got ${u.protocol}`);
  }
  return u;
}

const isHttpUrl = (raw: string): boolean => {
  try { const u = new URL(raw); return u.protocol === 'http:' || u.protocol === 'https:'; }
  catch { return false; }
};

try {
  await sender.sendNotifications(task, configs);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Push notification URL must use http or https')) {
    logger.warn('Rejecting push config with bad scheme', { err: err.message });
  } else throw err;
}

When it happens

Trigger: Registering/updating an A2A task push notification config whose `url` property uses a scheme other than http/https, e.g. 'ftp://example.com/callback', 'ws://...', or a malformed URL that parsed with an unexpected protocol.

Common situations: Typos like 'http:/host' or 'http//host', copying an internal callback URL with a custom scheme, misconfigured environment variables holding the push endpoint, or clients sending webhook URLs with protocols the library never supported.

Related errors

• Push notification host is not allowed: ${hostname}
• Push notification URL must not target local or internal host
• Push notification URL must not target local or private IPs:
• Push notification URL resolved to a local or private IP: ${h
• Push notification failed with status ${response.status} ${re

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/058b6302a72384f0. Report an issue: GitHub.