CopilotKit/CopilotKit · error

Missing or invalid parameter '${key}'

Error message

Missing or invalid parameter '${key}'

What it means

expectString(params, key) reads params[key] and requires a non-empty trimmed string; anything else (missing key, undefined, null, number, object, whitespace-only string) throws a 400 with the message 'Missing or invalid parameter \'<key\>'. It is used by resolveSingleRoute to validate envelope params before delegating to JSON handlers.

Source

Thrown at packages/runtime/src/v2/runtime/endpoints/single-route-helpers.ts:100

  const method = validateMethod(jsonEnvelope.method);

  return {
    method,
    params: jsonEnvelope.params,
    body: jsonEnvelope.body,
  };
}

export function expectString(
  params: Record<string, unknown> | undefined,
  key: string,
): string {
  const value = params?.[key];
  if (typeof value === "string" && value.trim().length > 0) {
    return value;
  }

  throw createResponseError(`Missing or invalid parameter '${key}'`, 400);
}

export function createJsonRequest(base: Request, body: unknown): Request {
  if (body === undefined || body === null) {
    throw createResponseError("Missing request body for JSON handler", 400);
  }

  const headers = new Headers(base.headers);
  headers.set("content-type", "application/json");
  headers.delete("content-length");

  const serializedBody = serializeJsonBody(body);

  return new Request(base.url, {
    method: "POST",
    headers,
    body: serializedBody,
    signal: base.signal,

View on GitHub (pinned to 68fbe97d87)

Solutions

1. Read the error message: the quoted key names the exact parameter to fix
2. Ensure every required parameter is a non-empty string (wrap numeric IDs with String(...) if needed)
3. Log the outgoing envelope on the client to spot missing/whitespace keys during development

Example fix

// before
{ method: 'agent/run', params: { threadId: 12345 } } // -> 400 Missing or invalid parameter 'threadId'

// after
{ method: 'agent/run', params: { threadId: '12345' } }

// Mirror the library's rule before sending
function expectString(params: Record<string, unknown>, key: string): string {
  const v = params?.[key];
  if (typeof v === 'string' && v.trim().length > 0) return v;
  throw new Error(`Missing or invalid parameter '${key}'`);
}
const threadId = expectString(envelope.params, 'threadId');

const isNonEmptyString = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

const res = await fetch(url, opts);
if (res.status === 400) {
  const body = await res.json().catch(() => null);
  const m = body?.error?.match(/parameter '(.+)'/);
  if (m) throw new Error(`Fix param '${m[1]}' in the outgoing envelope`);
}

When it happens

Trigger: Posting a method envelope whose params object omits a required key, passes a non-string value (e.g. threadId as a number), or passes a string of only whitespace. The key name in the message identifies exactly which parameter failed.

Common situations: Omitting required params like threadId or agentName when hand-crafting envelope payloads; client code passing coerced values (numbers, null) where IDs must be strings; version changes that introduce a new required parameter older clients don't send.

Related errors

• Invalid JSON payload
• Missing request body for JSON handler
• Request stream consumed with no available body; sending empt

AI-assisted analysis of CopilotKit/CopilotKit@68fbe97d87 (2026-08-27). Data as JSON: /api/errors/7283f1164b93266c. Report an issue: GitHub.