koala73/worldmonitor · error · Error

invalid X 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.

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.

Appendix: 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)