UnsupportedFlavorException

Learn what UnsupportedFlavorException is in Java, how it relates to clipboard operations and data transfer, and how to handle it properly using step-by-step examples.

This reference explains UnsupportedFlavorException through its syntax, examples and boundaries. Use the linked course lessons when the surrounding Java concepts are unfamiliar.

Use this reference
Identify the documented behavior, read a complete example and check its inputs before applying it.

Introduction to UnsupportedFlavorException

Java’s powerful GUI framework includes classes for interacting with the system clipboard and transferring data between applications. But when you request data in a format (or "flavor") that isn’t supported, Java throws an UnsupportedFlavorException.

This exception typically arises during clipboard operations or drag-and-drop data transfers when the requested DataFlavor doesn't match what’s available. In this beginner-friendly tutorial, we’ll break down this exception, show you why it occurs, and walk through practical, complete examples with clear explanations and expected outputs.

What is UnsupportedFlavorException?

UnsupportedFlavorException is a checked exception from the java.awt.datatransfer package. It indicates that a requested DataFlavor (data format) is not supported by the data being transferred.

Class Signature:

public class UnsupportedFlavorException extends Exception

This exception often occurs when using Transferable.getTransferData(DataFlavor flavor).

Common Use Cases

Reading from the system clipboard
Drag-and-drop data transfers
Custom implementations of Transferable

Understanding DataFlavor

Java · example discussed here

public class UnsupportedFlavorException extends Exception

DataFlavor represents the type of data format being transferred. For example, DataFlavor.stringFlavor is used to transfer plain text. If the data does not support this flavor, calling getTransferData() with it will result in UnsupportedFlavorException.

Example 1: Reading String Data from Clipboard

Step-by-step Program

import java.awt.datatransfer.*;
import java.awt.Toolkit;
import java.io.IOException;

public class ClipboardReader {
    public static void main(String[] args) {
        Clipboard clipboard = Toolkit.getDefaultToolkit().getSystemClipboard();

        try {
            Transferable contents = clipboard.getContents(null);

            if (contents != null && contents.isDataFlavorSupported(DataFlavor.stringFlavor)) {
                String text = (String) contents.getTransferData(DataFlavor.stringFlavor);
                System.out.println("Clipboard contains: " + text);
            } else {
                System.out.println("Clipboard does not contain string data.");
            }
        } catch (UnsupportedFlavorException e) {
            System.err.println("UnsupportedFlavorException: " + e.getMessage());
        } catch (IOException e) {
            System.err.println("IOException occurred while accessing clipboard.");
        }
    }
}

Expected Output (if clipboard contains a string):

Clipboard contains: Hello World

Expected Output (if clipboard contains image or unsupported data):

Clipboard does not contain string data.

This program checks if the clipboard supports stringFlavor. If not, it avoids calling getTransferData(), preventing the exception.

Example 2: Triggering UnsupportedFlavorException Intentionally

This example demonstrates what happens when we skip the flavor check and try to retrieve unsupported data directly.

public class ForceFlavorException {
    public static void main(String[] args) {
        Clipboard clipboard = Toolkit.getDefaultToolkit().getSystemClipboard();

        try {
            Transferable contents = clipboard.getContents(null);
            // Directly requesting imageFlavor even if it's not supported
            Object imageData = contents.getTransferData(DataFlavor.imageFlavor);
            System.out.println("Got image data: " + imageData);
        } catch (UnsupportedFlavorException e) {
            System.err.println("Caught UnsupportedFlavorException!");
        } catch (IOException e) {
            System.err.println("IOException occurred.");
        }
    }
}

Expected Output (if clipboard does not contain an image):

Caught UnsupportedFlavorException!

How to Handle UnsupportedFlavorException

1. Use Flavor Checks Before Accessing Data

Always check isDataFlavorSupported() before calling getTransferData().

if (contents.isDataFlavorSupported(DataFlavor.imageFlavor)) {
    Image img = (Image) contents.getTransferData(DataFlavor.imageFlavor);
}

2. Use Try-Catch Around Each Flavor

If you’re looping through multiple flavors, wrap each call in its own try block to isolate failures.

3. Provide Fallbacks or Warnings

When an exception is caught, display a user-friendly message or fallback option.

Creating a Custom Transferable Example

To really understand how flavors work, let’s create a custom Transferable that supports only stringFlavor.

class FruitTransferable implements Transferable {
    private String fruit = "banana";

    @Override
    public DataFlavor[] getTransferDataFlavors() {
        return new DataFlavor[]{ DataFlavor.stringFlavor };
    }

    @Override
    public boolean isDataFlavorSupported(DataFlavor flavor) {
        return DataFlavor.stringFlavor.equals(flavor);
    }

    @Override
    public Object getTransferData(DataFlavor flavor)
            throws UnsupportedFlavorException {
        if (isDataFlavorSupported(flavor)) {
            return fruit;
        } else {
            throw new UnsupportedFlavorException(flavor);
        }
    }
}

Test It:

public class TransferableTest {
    public static void main(String[] args) {
        FruitTransferable ft = new FruitTransferable();

        try {
            System.out.println("Fruit: " + ft.getTransferData(DataFlavor.stringFlavor));
            // Force error
            System.out.println("Image: " + ft.getTransferData(DataFlavor.imageFlavor));
        } catch (UnsupportedFlavorException e) {
            System.out.println("UnsupportedFlavorException caught: " + e.getFlavor().getHumanPresentableName());
        }
    }
}

Expected Output:

Fruit: banana
UnsupportedFlavorException caught: image