dotnet/aspnetcore · error · RuntimeException

TypeReference must be instantiated with a type parameter suc

Error message

TypeReference must be instantiated with a type parameter such as (new TypeReference<Foo<Bar>>() {}).

What it means

TypeReference uses super-type tokens (Gafter's Gadget) to reify generic types despite erasure. It requires an anonymous subclass that supplies a concrete type argument, e.g. new TypeReference<Foo<Bar>>(){}. If instantiated as a raw new TypeReference(), the generic superclass is not a ParameterizedType and the cast fails.

Source

Thrown at src/SignalR/clients/java/signalr/core/src/main/java/com/microsoft/signalr/TypeReference.java:40

     * spite of type erasure since, sadly, {@code Foo<Bar>.class} is not valid Java.
     *
     * To get the Type of Class {@code Foo<Bar>}, use the following syntax:
     * <pre>{@code
     * Type fooBarType = (new TypeReference<Foo<Bar>>() { }).getType();
     * }</pre>
     *
     * To get the Type of class Foo, use a regular Type Token:
     * <pre>{@code
     * Type fooType = Foo.class;
     * }</pre>
     *
     *  @see <a href="http://gafter.blogspot.com/2006/12/super-type-tokens.html">Super Type Tokens</a>
     */
    public TypeReference() {
        try {
            this.type = ((ParameterizedType) getClass().getGenericSuperclass()).getActualTypeArguments()[0];
        } catch (ClassCastException ex) {
            throw new RuntimeException("TypeReference must be instantiated with a type parameter such as (new TypeReference<Foo<Bar>>() {}).");
        }
    }

    /**
     * Gets the referenced type.
     * @return The Type encapsulated by this TypeReference
     */
    public Type getType() {
        return this.type;
    }
}

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Always instantiate as an anonymous class with the concrete type argument: new TypeReference<Map<String,Integer>>(){}.
2. For non-generic types use the plain Class token (Foo.class) instead of TypeReference.

Example fix

// before
Type t = new TypeReference();

// after
Type t = new TypeReference<Map<String, Integer>>() {}.getType();

// Java - ensure a TypeReference is parameterized before using it
static boolean isParameterized(TypeReference<?> ref) {
    return ref.getClass().getGenericSuperclass() instanceof java.lang.reflect.ParameterizedType;
}

When it happens

Trigger: Writing new TypeReference() with no type argument; omitting the {} anonymous-class body; assigning to a raw TypeReference variable; subclassing TypeReference concretely without a fixed generic.

Common situations: Deserializing a generic hub-method return type (List<Foo>, Map<String,Integer>); IDE auto-completed the constructor without the generic braces; copy-paste dropped the (){}.

Related errors

• Cannot handle type class: ${type.getClass()}
• '%s' already has a value returning handler. Multiple return
• Expected either 'error' or 'result' to be provided, but not
• Message is incomplete.
• The message type %s is not supported yet.

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/06c30b65af07f1fe. Report an issue: GitHub.