openclaw/openclaw · error · CatalogParamsError

unknown Codex session catalog parameter: ${unknown}

Error message

unknown Codex session catalog parameter: ${unknown}

What it means

Thrown as CatalogParamsError by requireOnlyKeys in session-catalog-parsing.ts:210 when the params object contains any key not in the allowed set. readPageParams allows {cursor, limit, searchTerm, cwd}; readGatewayParams allows {search, limitPerHost, hostIds, cursors}. The offending key name is included in the message.

Source

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

    throw new CatalogParamsError(`${key} must be a string`);
  }
  const trimmed = value.trim();
  if (!trimmed) {
    return undefined;
  }
  if (trimmed.length > maxLength) {
    throw new CatalogParamsError(`${key} must be at most ${maxLength} characters`);
  }
  return trimmed;
}

export function requireOnlyKeys(
  params: Record<string, unknown>,
  allowed: ReadonlySet<string>,
): void {
  const unknown = Object.keys(params).find((key) => !allowed.has(key));
  if (unknown) {
    throw new CatalogParamsError(`unknown Codex session catalog parameter: ${unknown}`);
  }
}

export function readPageParams(value: unknown): CodexSessionCatalogPageParams {
  if (!isRecord(value)) {
    throw new CatalogParamsError("Codex session catalog parameters must be an object");
  }
  const params = value;
  requireOnlyKeys(params, new Set(["cursor", "limit", "searchTerm", "cwd"]));
  const cursor = readBoundedOptionalString(params, "cursor", MAX_CURSOR_LENGTH);
  const searchTerm = readBoundedOptionalString(params, "searchTerm", MAX_SEARCH_LENGTH);
  const cwd = readBoundedOptionalString(params, "cwd", MAX_CWD_LENGTH);
  return {
    limit: normalizeLimit(params.limit, "limit"),
    ...(cursor ? { cursor } : {}),
    ...(searchTerm ? { searchTerm } : {}),
    ...(cwd ? { cwd } : {}),
  };

View on GitHub (pinned to 01804a7531)

Solutions

1. Send only the keys listed in the allowed set for the reader you are targeting.
2. Remove typo'd or debug fields before constructing the params object.
3. Confirm you are calling readPageParams for page-level params and readGatewayParams for gateway-level params.
4. After upgrading OpenClaw, check the changelog for newly allowed keys if you want to use them.

Example fix

// before
readPageParams({ cursor, limit, limt: 5 }); // throws: unknown key 'limt'

// after
readPageParams({ cursor, limit });

// Allow-list keys before forwarding to readPageParams / readGatewayParams.
const PAGE_ALLOWED = new Set(['cursor', 'limit', 'searchTerm', 'cwd']);
const filtered = Object.fromEntries(
  Object.entries(raw).filter(([k]) => PAGE_ALLOWED.has(k)),
);
readPageParams(filtered);

When it happens

Trigger: Passing a typo'd key (e.g. 'limt' instead of 'limit'), an extra unsupported field, or params shaped for the wrong reader (gateway params passed to readPageParams or vice versa).

Common situations: Client copies params from one endpoint to another without filtering; SDK version added a new allowed key the caller's build does not recognise (reverse case); UI forwards a debug field.

Related errors

• ${key} must be a string
• ${key} must be at most ${maxLength} characters
• Codex session catalog parameters must be an object
• Codex session catalog hostId is invalid
• paired node does not permit Codex session continuation

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