decolua/9router · error

AWS EventStream header ${name} has unknown type ${type}

Error message

AWS EventStream header ${name} has unknown type ${type}

What it means

EventStream header values carry a 1-byte type code (0..13 in the AWS spec: true/false, int8/16/32/64, byte arrays, strings, timestamps, UUIDs). parseEventFrame() only implements the types Kiro actually uses; when it encounters a type code outside the implemented set it throws this error naming the header and the unknown type, since it cannot decode the value safely.

Source

Thrown at open-sse/executors/kiro.js:1267

      requireBytes(4);
      headers[name] = view.getInt32(offset, false);
      offset += 4;
    } else if (type === 5 || type === 8) {
      requireBytes(8);
      offset += 8;
    } else if (type === 6 || type === 7) {
      requireBytes(2);
      const valueLength = view.getUint16(offset, false);
      offset += 2;
      requireBytes(valueLength);
      const bytes = data.subarray(offset, offset + valueLength);
      headers[name] = type === 7 ? decoder.decode(bytes) : bytes;
      offset += valueLength;
    } else if (type === 9) {
      requireBytes(16);
      offset += 16;
    } else {
      throw new Error(`AWS EventStream header ${name} has unknown type ${type}`);
    }
  }

  const payloadBytes = data.subarray(headerEnd, totalLength - 4);
  if (payloadBytes.byteLength === 0) return { headers, payload: null };
  const payloadText = decoder.decode(payloadBytes);
  if (!payloadText.trim()) return { headers, payload: null };
  try {
    return { headers, payload: JSON.parse(payloadText) };
  } catch (error) {
    throw new Error(`AWS EventStream payload is not valid JSON (${error.message})`);
  }
}

export default KiroExecutor;

View on GitHub (pinned to 90b52e06ff)

Solutions

  1. Update 9router to the latest version — new header types are added to the parser as Kiro's protocol evolves
  2. Log the frame as hex and note the header name/type shown in the message; if type 5/6/8 etc., it is a genuine protocol addition needing a parser update
  3. Retry the request; if the error appears only sporadically it is likely corruption rather than protocol drift
  4. Bypass proxies that rewrite binary bodies to rule out byte misalignment
  5. Report the header name and type from the message to the 9router maintainers if the latest version still throws

Example fix

// before (kiro.js parser)
} else {
  throw new Error(`AWS EventStream header ${name} has unknown type ${type}`);
}
// after (workaround: skip unsupported fixed-size types)
} else if (type === 5 || type === 6) { requireBytes(8); offset += 8; headers[name] = null;
} else {
  throw new Error(`AWS EventStream header ${name} has unknown type ${type}`);
}
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await executor.execute(req);
} catch (e) {
  const m = e.message.match(/unknown type (\d+)/);
  if (m) {
    log.warn('unsupported eventstream header type', { type: +m[1] });
    return retryOrFallback(req);
  }
  throw e;
}

Prevention

When it happens

Trigger: A Kiro frame contains a header whose type byte is not one of the implemented codes (e.g. 5/6/8/10..13 — 64-bit ints, timestamps, UUID variants). This happens when Kiro's backend starts emitting a new header type, or when corrupted data shifts the type-byte position so a random byte is read as the type.

Common situations: Kiro ships a protocol update adding new header types before the parser supports them; corrupted stream data from a proxy misaligns the header walk so a value byte is misread as a type code; running a stale 9router version against a newer upstream.

Related errors

AI-assisted analysis of decolua/9router@90b52e06ff (2026-08-30). Data as JSON: /api/errors/1022c7b0d32bf5b5. Report an issue: GitHub.