google/ExoPlayer · error · IllegalStateException

Missing implementation to handle COMMAND_CHANGE_MEDIA_ITEMS

Error message

Missing implementation to handle COMMAND_CHANGE_MEDIA_ITEMS

What it means

Player.addMediaItem/addMediaItems route through SimpleBasePlayer.handleAddMediaItems(int index, List<MediaItem>). The default throws IllegalStateException when COMMAND_CHANGE_MEDIA_ITEMS appears in availableCommands without the override. The handler is only invoked if the player is not in STATE_IDLE (SimpleBasePlayer requires a prepared state before playlist mutation).

Source

Thrown at library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java:3198

  protected ListenableFuture<?> handleSetMediaItems(
      List<MediaItem> mediaItems, int startIndex, long startPositionMs) {
    throw new IllegalStateException("Missing implementation to handle COMMAND_SET_MEDIA_ITEM(S)");
  }

  /**
   * Handles calls to {@link Player#addMediaItem} and {@link Player#addMediaItems}.
   *
   * <p>Will only be called if {@link Player#COMMAND_CHANGE_MEDIA_ITEMS} is available.
   *
   * @param index The index at which to add the items. The index is in the range 0 &lt;= {@code
   *     index} &lt;= {@link #getMediaItemCount()}.
   * @param mediaItems The media items to add.
   * @return A {@link ListenableFuture} indicating the completion of all immediate {@link State}
   *     changes caused by this call.
   */
  @ForOverride
  protected ListenableFuture<?> handleAddMediaItems(int index, List<MediaItem> mediaItems) {
    throw new IllegalStateException("Missing implementation to handle COMMAND_CHANGE_MEDIA_ITEMS");
  }

  /**
   * Handles calls to {@link Player#moveMediaItem} and {@link Player#moveMediaItems}.
   *
   * <p>Will only be called if {@link Player#COMMAND_CHANGE_MEDIA_ITEMS} is available.
   *
   * @param fromIndex The start index of the items to move. The index is in the range 0 &lt;= {@code
   *     fromIndex} &lt; {@link #getMediaItemCount()}.
   * @param toIndex The index of the first item not to be included in the move (exclusive). The
   *     index is in the range {@code fromIndex} &lt; {@code toIndex} &lt;= {@link
   *     #getMediaItemCount()}.
   * @param newIndex The new index of the first moved item. The index is in the range {@code 0}
   *     &lt;= {@code newIndex} &lt; {@link #getMediaItemCount() - (toIndex - fromIndex)}.
   * @return A {@link ListenableFuture} indicating the completion of all immediate {@link State}
   *     changes caused by this call.
   */
  @ForOverride

View on GitHub (pinned to dd430f7053)

Solutions

Override handleAddMediaItems(int index, List<MediaItem> mediaItems): splice the items into the existing playlist at index and return an immediate future after invalidating state.
Or stop advertising COMMAND_CHANGE_MEDIA_ITEMS if the playlist must be immutable.
Implement add, move, remove and replace handlers as a unit since they share the same command.

Example fix

// before
// availableCommands includes COMMAND_CHANGE_MEDIA_ITEMS, no override:

// after
@Override
protected ListenableFuture<?> handleAddMediaItems(int index, List<MediaItem> mediaItems) {
  List<MediaItem> playlist = new ArrayList<>(state.playlist);
  playlist.addAll(index, mediaItems);
  state = state.buildUpon().setPlaylist(playlist).build();
  invalidateState();
  return Futures.immediateVoidFuture();
}

Defensive patterns

Strategy: validation

Validate before calling

if (player.isCommandAvailable(Player.COMMAND_CHANGE_MEDIA_ITEMS)) {
  checkOverrides(playerClass, "handleAddMediaItems");
}

Prevention

Implement add, move, remove and replace handlers together — one command gates them all.
Remember playlist mutation handlers are only called when not in STATE_IDLE.
Clamp or verify the index argument against getMediaItemCount() in your backing store.

When it happens

Trigger: Calling player.addMediaItem(item) or addMediaItems(index, items) on a custom SimpleBasePlayer that declares COMMAND_CHANGE_MEDIA_ITEMS but does not override handleAddMediaItems.

Common situations: Implementing setMediaItems for basic playback but not the incremental add variants; queue-building apps (podcast/video queues) calling addMediaItem repeatedly against a wrapper player.

Related errors

AI-assisted analysis of google/ExoPlayer@dd430f7053 (2026-08-14). Data as JSON: /api/errors/81ccbc78de4ee7a6. Report an issue: GitHub.