koala73/worldmonitor · error · Error

invalid X handle: ${handle}

Error message

invalid X handle: ${handle}

What it means

Contract validation error from normalizeXHandle: after stripping a leading '@' and lowercasing, the handle does not match the X_HANDLE pattern. The offending handle is included in the message. Inputs like full URLs, display names, or handles with invalid characters trigger this.

Source

Thrown at shared/company-monitoring-contract.ts:122

}

function normalizeDomain(value: unknown, index: number): string {
  const domain = assertPlainText(
    value,
    `domains[${index}]`,
    COMPANY_MONITORING_LIMITS.maxDomainBytes,
  ).toLowerCase().replace(/^www\./, '').replace(/\.$/, '');
  if (!DOMAIN.test(domain)) throw new Error(`invalid domain: ${domain}`);
  return domain;
}

function normalizeXHandle(value: unknown, index: number): string {
  const handle = assertPlainText(
    value,
    `xHandles[${index}]`,
    COMPANY_MONITORING_LIMITS.maxXHandleInputBytes,
  ).replace(/^@/, '').toLowerCase();
  if (!X_HANDLE.test(handle)) throw new Error(`invalid X handle: ${handle}`);
  return handle;
}

const DOMICILE_COUNTRY_BY_INPUT = {
  US: 'US',
  GB: 'GB',
  DOMICILE_COUNTRY_US: 'US',
  DOMICILE_COUNTRY_GB: 'GB',
} as const;

export type CompanyClaimType =
  | 'alias'
  | 'domain'
  | 'legal_identifier'
  | 'x_account_id'
  | 'x_handle'
  | 'location'
  | 'customer_reference';

View on GitHub (pinned to eeab0a219f)

Solutions

1. Send the bare handle (e.g. 'acme' or '@acme'; the @ is stripped automatically), not a full x.com URL
2. Remove spaces and characters disallowed in X handles

When it happens

Trigger: Thrown at shared/company-monitoring-contract.ts:122 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of koala73/worldmonitor@eeab0a219f (2026-08-21). Data as JSON: /api/errors/baf967de5ee206ad. Report an issue: GitHub.