mastra-ai/mastra · error

Unknown chunk type: ${exhaustiveCheck}

Error message

Unknown chunk type: ${exhaustiveCheck}

What it means

convertFullStreamChunkToUIMessageStream translates internal stream chunks into AI SDK v5 UI message stream parts. The default branch is an exhaustiveness check; it throws when a chunk type arrives that has no mapping — usually a new/unknown Mastra chunk type or a mismatch between core and the v5 compat layer versions.

Source

Thrown at packages/core/src/stream/aisdk/v5/compat/ui-message.ts:247

    }

    case 'abort': {
      return part;
    }

    case 'tool-input-end': {
      return;
    }

    case 'raw': {
      // Raw chunks are not included in UI message streams
      // as they contain provider-specific data for developer use
      return;
    }

    default: {
      const exhaustiveCheck: never = partType;
      throw new Error(`Unknown chunk type: ${exhaustiveCheck}`);
    }
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Align versions: upgrade @mastra/core (and related stream packages) together so all chunk types have mappings
  2. Log partType from the error to identify the unhandled chunk and check whether a newer release handles it
  3. Filter or transform unknown chunks in custom stream middleware before they reach the converter
  4. Report the chunk type as an issue if it comes from an officially supported provider

Example fix

// before
pnpm add @mastra/core@0.10 @mastra/ai-sdk@0.9
// after
pnpm add @mastra/core@latest @mastra/ai-sdk@latest  # matching versions
Defensive patterns

Strategy: try-catch

Type guard

type KnownChunkType = 'text-delta' | 'reasoning-delta' | 'tool-call' | /* ... */;
function isKnownChunkType(t: string): t is KnownChunkType {
  // keep in sync with convertFullStreamChunkToUIMessageStream's switch
  return KNOWN_CHUNK_TYPES.has(t as KnownChunkType);
}

Try / catch

try {
  for await (const part of uiMessageStream) { render(part); }
} catch (e) {
  if (String(e).startsWith('Unknown chunk type:')) {
    logger.error('Unhandled stream chunk', { partType: String(e).split(': ')[1] });
    // degrade gracefully: finish the message with what was rendered so far
  } else throw e;
}

Prevention

When it happens

Trigger: Streaming with a model/provider emitting chunk types not yet handled (e.g. a new provider event), or a core chunk type added after this compat converter was written; custom middleware injecting unknown chunk types.

Common situations: Upgrading @mastra/core without upgrading stream/aisdk compat pieces (or vice versa); using a provider plugin that forwards proprietary chunks; manually pushing chunks into the stream pipeline.

Related errors

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