UI Messages require a data property when using data- prefixe

Error message

UI Messages require a data property when using data- prefixed chunks 
 ${JSON.stringify(payload)}

What it means

Same family as the other data-chunk errors: in the default branch of the stream transformer, an unknown chunk that is recognized as a data- prefixed type must contain a 'data' property to be convertible to a UI message part. This variant runs on the plain payload path of transformers.ts.

Source

Thrown at client-sdks/ai-sdk/src/transformers.ts:1199

        return transformedChunk;
      }

      if (output && isDataChunkType(output)) {
        if (!('data' in output)) {
          throw new Error(
            `UI Messages require a data property when using data- prefixed chunks \n ${JSON.stringify(output)}`,
          );
        }
        const { type, data, id } = output;
        return { type, data, ...(id !== undefined && { id }) };
      }
      return null;
    }
    default: {
      // return the chunk as is if it's not a known type
      if (isDataChunkType(payload)) {
        if (!('data' in payload)) {
          throw new Error(
            `UI Messages require a data property when using data- prefixed chunks \n ${JSON.stringify(payload)}`,
          );
        }
        const { type, data, id } = payload;

        return {
          type,
          data,
          ...(id !== undefined && { id }),
        };
      }
      return null;
    }
  }
}

type TransformNetworkResult = InferUIMessageChunk<UIMessage> | NetworkDataPart | DataChunkType | WorkflowStepDataPart;

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure every data- chunk includes data: { type: 'data-x', data: {...} }.
Validate chunk shape before writing to the stream (typeof chunk.data !== 'undefined').
If the chunk is meant to be opaque, prefix the type differently so it is not treated as a data chunk.
Inspect the JSON in the error message to identify which emitter produced it.

Example fix

// before
return { type: 'data-notification' };
// after
return { type: 'data-notification', data: { message: 'Done' } };

Defensive patterns

Strategy: type-guard

Validate before calling

if (isDataChunkType(payload) && !('data' in payload)) {
  throw new Error(`data chunk ${payload.type} missing data`);
}

Type guard

function isCompleteDataChunk(p: unknown): p is { type: string; data: unknown; id?: string } {
  return typeof p === 'object' && p !== null && 'type' in p && String((p as any).type).startsWith('data-') && 'data' in p;
}

Try / catch

try {
  return transformChunk(payload);
} catch (e) {
  if (e instanceof Error && e.message.includes('require a data property')) {
    return null; // skip malformed chunk
  }
  throw e;
}

Prevention

Validate chunk shape before writing to any stream.
Use a discriminated union type for all chunk kinds.
Don't rename the payload key away from 'data'.

When it happens

Trigger: Writing a custom data chunk ({ type: 'data-x', ... }) through the agent stream-to-UIMessage transformer without a data property; the chunk passes isDataChunkType but lacks 'data'.

Common situations: Server-side tool output objects accidentally forwarded as chunks without wrapping; conditionally-built chunk objects where data is left out on some branches; refactors renaming the payload key.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/09068b9be6a03a19. Report an issue: GitHub.