What causes "Byte array index '${index}' does not exist." in dotnet/aspnetcore?

If you custom-frame interop, always call receiveByteArray(id, bytes) before reviving the JSON that references that id.

Byte array index '${index}' does not exist.

Error message

Byte array index '${index}' does not exist.

What it means

Thrown in the reviveReference reviver when a payload carries a byte-array marker {byteArrayIndex: N} but processByteArray(index) (Microsoft.JSInterop.ts:505) returns nothing for that index. Byte arrays are pre-staged via receiveByteArray(id, data) before the JSON referencing them is revived; if the staging call was missed, mismatched, or already consumed, the index is absent. Note: the guard compares against 'undefined' while processByteArray returns null, so this branch is effectively unreachable in current code; the intent is to flag a missing staged byte array.

Source

Thrown at src/JSInterop/Microsoft.JSInterop.JS/src/src/Microsoft.JSInterop.ts:744

  attachReviver(function reviveReference(key: any, value: any) {
      if (value && typeof value === "object") {
          if (value.hasOwnProperty(dotNetObjectRefKey)) {
              return new DotNetObject(value[dotNetObjectRefKey], currentCallDispatcher!);
          } else if (value.hasOwnProperty(jsObjectIdKey)) {
              const id = value[jsObjectIdKey];
              const jsObject = cachedJSObjectsById[id];

              if (jsObject) {
                  return jsObject.getWrappedObject();
              }

              throw new Error(`JS object instance with Id '${id}' does not exist. It may have been disposed.`);
          } else if (value.hasOwnProperty(byteArrayRefKey)) {
              const index = value[byteArrayRefKey];
              const byteArray = currentCallDispatcher!.processByteArray(index);
              if (byteArray === undefined) {
                  throw new Error(`Byte array index '${index}' does not exist.`);
              }
              return byteArray;
          } else if (value.hasOwnProperty(dotNetStreamRefKey)) {
              const streamId = value[dotNetStreamRefKey];
              const streamPromise = currentCallDispatcher!.getDotNetStreamPromise(streamId);
              return new DotNetStream(streamPromise);
          }
      }

      // Unrecognized - let another reviver handle it
      return value;
  });

  class DotNetStream {
      // eslint-disable-next-line no-empty-function
      constructor(private readonly _streamPromise: Promise<ReadableStream>) {
      }

View on GitHub (pinned to 294cab2f9b)

Solutions

If you custom-frame interop, always call receiveByteArray(id, bytes) before reviving the JSON that references that id.
Avoid reusing/ replaying captured payloads; let the framework produce them.
On framework versions, report the issue if it reproduces with stock framing (the null/undefined guard should be tightened).
Validate on the .NET side that byte arrays are sent via the supported API (IJSRuntime byte-array marshalling).

Example fix

// before (custom framing)
// dispatcher revives JSON with {byteArrayIndex: 7} but never called receiveByteArray(7, data)

// after
dotNetCallDispatcher.receiveByteArray(7, bytes);
const value = parseJsonWithRevivers(dispatcher, jsonWithRef);

Defensive patterns

Strategy: validation

Validate before calling

// when custom-framing, stage the byte array before reviving
dotNetCallDispatcher.receiveByteArray(id, bytes);
const value = parseJsonWithRevivers(dotNetCallDispatcher, json);

Type guard

null

Try / catch

try { JSON.parse(json, defaultReviver); } catch (e) { if (/Byte array index/.test(e.message)) { /* re-stage then retry */ } else throw e; }

Prevention

Always call receiveByteArray before reviving byte-array-referencing JSON.
Avoid replaying captured interop payloads in fresh runtimes.
Let the framework produce byte-array framing rather than hand-rolling it.

When it happens

Trigger: A byte-array-bearing payload arriving without its preceding receiveByteArray call; a duplicated receiveByteArray consuming the same index twice; out-of-order framing where the JSON arrives before the byte staging; a custom serializer that omits the staging step. In shipped framing this is normally impossible, which is why the mismatched null/undefined check went unnoticed.

Common situations: Custom transports or test harnesses that hand-construct interop payloads; a framing regression; passing Uint8Array/IAsyncEnumerable byte segments out of order.

Related errors

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/f0b5e4b519e9cb05. Report an issue: GitHub.