github/copilot-sdk · error · ResponseError

nested_undefined

nested_undefined

Error message

${context.label} contains nested undefined at ${path}

What it means

strictJsonValidationError is thrown by the strict JSON validation walker when a value destined for JSON serialization contains undefined at a nested path where undefined is not allowed. JSON.stringify silently drops undefined values, so this library fails fast instead of sending a silently-mangled payload. The error carries code=nested_undefined and the offending path.

Solutions

1. Read the error's path field to locate the offending property and ensure it is defined before the call, or delete the key entirely instead of leaving it undefined.
2. Use a sanitizer that strips undefined values recursively before calling the API.
3. Fix the source of the undefined value (missing config, unset variable, absent function argument).
4. If undefined is legitimately allowed at that spot, use the API variant/flag that permits undefined (allowUndefined) if one exists.

Example fix

// before
await session.send({
  prompt: userPrompt,
  context: { filter: maybeFilter } // maybeFilter may be undefined
});
// after
const payload = { prompt: userPrompt, context: {} };
if (maybeFilter !== undefined) {
  payload.context.filter = maybeFilter;
}
await session.send(payload);

function assertNoUndefined(value: unknown, path = 'root'): void {
  if (value === undefined) throw new Error(`undefined at ${path}`);
  if (Array.isArray(value)) value.forEach((v, i) => assertNoUndefined(v, `${path}[${i}]`));
  else if (value && typeof value === 'object') {
    for (const [k, v] of Object.entries(value)) assertNoUndefined(v, `${path}.${k}`);
  }
}
// call assertNoUndefined(payload) before session.send(payload)

function isJsonSafe(v: unknown): boolean {
  try { JSON.stringify(v); return true; } catch { return false; }
}
// note: JSON.stringify hides undefined; pair with assertNoUndefined above

try {
  await session.send(payload);
} catch (error) {
  if ((error as { code?: string }).code === 'nested_undefined') {
    console.error('Payload has undefined at:', (error as { path?: string }).path);
  } else {
    throw error;
  }
}

When it happens

Trigger: Passing an object to a session API validated by strict JSON validation (e.g. message payloads, tool arguments, or factory inputs) that contains an explicitly-undefined nested property, or an array hole / undefined element, at a path where allowUndefined is false.

Common situations: Building payloads by conditionally spreading fields where a variable is undefined; reading a missing config value into the payload; optional function parameters forwarded directly into the request object; sparse arrays.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unexpected trailing content at position
• non_finite_number
• negative_zero
• unsupported_type
• cyclic_value

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/ec45edaefd16ce85. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/session.ts:2299

    return new ResponseError(ErrorCodes.InternalError, message, {
        code: context.code,
        category,
        path,
    });
}

function assertStrictJson(
    value: unknown,
    context: StrictJsonValidationContext
): asserts value is JsonValue | undefined {
    const ancestors = new Set<object>();

    const visit = (current: unknown, path: string, allowUndefined: boolean): void => {
        if (current === undefined) {
            if (allowUndefined) {
                return;
            }
            throw strictJsonValidationError(
                context,
                "nested_undefined",
                `${context.label} contains nested undefined at ${path}`,
                path
            );
        }
        if (current === null || typeof current === "boolean" || typeof current === "string") {
            return;
        }
        if (typeof current === "number") {
            if (!Number.isFinite(current)) {
                throw strictJsonValidationError(
                    context,
                    "non_finite_number",
                    `${context.label} contains a non-finite number at ${path}`,
                    path
                );
            }

View on GitHub (pinned to cd8cf15dc3)