openclaw/openclaw · error · CatalogParamsError

invalid Codex session catalog host id: ${value}

Error message

invalid Codex session catalog host id: ${value}

What it means

Thrown by readHostId when a hostIds entry, after trimming, is empty, longer than MAX_HOST_ID_LENGTH (256), or does not start with 'gateway:' or 'node:'. This is the array-entry counterpart of the cursors-key validation.

Source

Thrown at extensions/codex/src/session-catalog-parsing.ts:292

  return {
    limitPerHost: normalizeLimit(params.limitPerHost, "limitPerHost"),
    ...(search ? { search } : {}),
    ...(hostIds && hostIds.length > 0 ? { hostIds } : {}),
    ...(cursors && Object.keys(cursors).length > 0 ? { cursors } : {}),
  };
}

function readHostId(value: unknown): string {
  if (typeof value !== "string") {
    throw new CatalogParamsError("Codex session catalog host ids must be strings");
  }
  const hostId = value.trim();
  if (
    hostId.length === 0 ||
    hostId.length > MAX_HOST_ID_LENGTH ||
    (!hostId.startsWith("gateway:") && !hostId.startsWith("node:"))
  ) {
    throw new CatalogParamsError(`invalid Codex session catalog host id: ${value}`);
  }
  return hostId;
}

export function parseJsonParams(paramsJSON?: string | null): unknown {
  if (!paramsJSON?.trim()) {
    return {};
  }
  try {
    return JSON.parse(paramsJSON) as unknown;
  } catch (error) {
    throw new Error("Codex session catalog parameters must be valid JSON", { cause: error });
  }
}

function readFiniteNumber(value: unknown): number | undefined {
  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
}

View on GitHub (pinned to 01804a7531)

Solutions

1. Use the full prefixed host id form: 'gateway:local' or 'node:<nodeId>'.
2. Filter out empty/whitespace entries before serializing.

Example fix

// before
const hostIds = [nodeId];
// after
const hostIds = [`node:${nodeId}`];

function isPrefixedHost(value: string): boolean {
  const t = value.trim();
  return t.length > 0 && t.length <= 256 && (t.startsWith("gateway:") || t.startsWith("node:"));
}
params.hostIds = (params.hostIds ?? []).filter(isPrefixedHost);

function isHostId(value: unknown): value is string {
  if (typeof value !== "string") return false;
  const t = value.trim();
  return t.length > 0 && t.length <= 256 && (t.startsWith("gateway:") || t.startsWith("node:"));
}

When it happens

Trigger: Passing hostIds like ["localhost"], [" "], ["node:"], or an unprefixed node uuid.

Common situations: Forgetting the prefix when forwarding a raw node id; including a placeholder empty string from a UI dropdown.

Related errors

• hostIds must contain at most ${MAX_HOST_COUNT} host ids
• cursors must be an object
• cursors may contain at most ${MAX_CURSOR_COUNT} hosts
• invalid Codex session catalog host id: ${hostId}
• invalid cursor for Codex session catalog host: ${hostId}

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/24cef2b9823b53cc. Report an issue: GitHub.