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(output)}

What it means

The AI SDK stream transformer converts custom 'data-' prefixed chunks into UI message parts. A data- chunk must carry a 'data' property holding its payload; this library throws when a data- typed chunk arrives without one, since it cannot build a valid UI data part from it.

Source

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

            )
            .filter(Boolean);
        }

        const transformedChunk = convertFullStreamChunkToUIMessageStream({
          part: part as any,
          sendReasoning: streamOptions?.sendReasoning,
          sendSources: streamOptions?.sendSources,
          onError(error) {
            return safeParseErrorObject(error);
          },
        });

        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;

View on GitHub (pinned to 75dd419e61)

Solutions

Always include a data property on data- prefixed chunks: { type: 'data-foo', data: {...} }.
Guard the payload before writing: skip or default the chunk if data is undefined.
Check the field name — the payload must be under 'data', not 'payload' or 'value'.
Log the offending chunk (included in the error JSON) to find the emitter.

Example fix

// before
writer.write({ type: 'data-weather', id: 'w1' }); // missing data
// after
writer.write({ type: 'data-weather', id: 'w1', data: { forecast: 'sunny' } });

Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

function hasDataProp(c: { type: string }): c is { type: string; data: unknown } {
  return 'data' in c && c.data !== undefined;
}

Try / catch

try {
  writer.write(chunk);
} catch (e) {
  if (e instanceof Error && e.message.includes('require a data property')) {
    console.error('Bad chunk:', e.message);
  } else throw e;
}

Prevention

Type custom data chunks as { type: `data-${string}`; data: unknown }.
Never emit data- chunks conditionally without their data field.
Centralize chunk creation in helper functions that enforce the shape.

When it happens

Trigger: Emitting a chunk like { type: 'data-myThing' } (or calling writer.write with such an object) from a tool/agent without including { data: ... } in the chunk, in the agent stream transformer path (transformers.ts:1186).

Common situations: Custom data chunk creation where 'data' is omitted because it's undefined/null at runtime; mistyping the payload field name (e.g. 'payload' instead of 'data'); spreading an object that drops the data key when empty.

Related errors

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