Common Compiler Errors

Diagnosing what the annotation processor and type checker tell you

This page is for the moment a build fails and you want to know what the message means. Find the fragment your compiler printed in the table below and follow it to its entry. Every entry says what the message means, gives the fix, and keeps the reasoning in a Why you can open if you want it.

Find your message

From @GenerateLenses, @GenerateFocus, @GenerateTraversals and friends (entries):

From @ImportOptics and spec interfaces (entries):

From @GeneratePathBridge and @PathVia (entries):

From javac, on code you wrote (Focus DSL chains, Free Monad):

Where the message came from

Three different things can reject your code, and knowing which one spoke narrows the search:

flowchart TD
    D["Your declaration<br/>@Generate*, or a spec interface"]
    P{"Does the processor<br/>accept it?"}
    R["Refused at your declaration.<br/>Most of this page"]
    G["Generated file written"]
    J{"Does javac accept<br/>the generated file?"}
    JG["cannot find symbol,<br/>inside a class you did not write"]
    C{"Does javac accept<br/>your call site?"}
    CC["Focus DSL chain and<br/>Free Monad errors"]
    OK(["Builds"])

    D --> P
    P -->|no| R
    P -->|yes| G
    G --> J
    J -->|no| JG
    J -->|yes| C
    C -->|yes| OK
    C -->|no| CC

    classDef step fill:#8caaee,stroke:#1e66f5,color:#232634
    classDef decision fill:#e5c890,stroke:#df8e1d,color:#232634
    classDef error fill:#e78284,stroke:#d20f39,color:#232634
    classDef ok fill:#a6d189,stroke:#40a02b,color:#232634
    class D,G step
    class P,J,C decision
    class R,JG,CC error
    class OK ok

Most of this page is the first branch. The processor reads your declaration, finds a shape it cannot write code for, and says so where you wrote it. Those messages name the element they rejected, so reading the processor's own output first is quicker than working backwards from a cannot find symbol further down the build.

A cannot find symbol: class XLenses sits outside the diagram altogether: it means the processor never ran.

@GenerateLenses / @GenerateFocus / @GenerateTraversals

"cannot find symbol: class XLenses"

The annotation processor has not run yet, or the IDE has not picked up the generated sources directory.

Fix. Run a build (./gradlew build or mvn compile). After the build completes, refresh the project in your IDE so it indexes build/generated/sources/annotationProcessor/java/main (Gradle) or target/generated-sources/annotations (Maven).

"@GenerateLenses: can only be applied to records, but 'Foo' is a class"

@GenerateLenses, @GenerateFocus, @GenerateFolds, @GenerateGetters, @GenerateSetters and @GenerateTraversals only apply to records.

Fix. Convert the class to a record. If the type is third-party and you cannot change it, use @ImportOptics on a package-info.java or a spec interface instead.

@GenerateLenses
class Order {}

"The @GeneratePrisms annotation can only be applied to sealed interfaces or enums."

@GeneratePrisms requires a sealed interface or an enum. A sealed abstract class is rejected too, despite being sealed, because the processor tests the element kind rather than the modifier.

Fix. Make the type a sealed interface and declare its permits clause, or convert it to an enum.

@GeneratePrisms
abstract class Payment {}

"@GenerateIsos: the iso returned by 'x' names a type variable"

One of the returned Iso's two type arguments is, or contains, a type variable. Both <T> Iso<Box<T>, T> boxIso() and an instance method of a Holder<X> returning Iso<Box<X>, X> do this.

Fix. Give the iso concrete type arguments where the method is declared (Iso<Box<String>, String>), or drop @GenerateIsos and call the method directly.

record Box<T>(T content) {}

final class BoxIsos {

    @GenerateIsos
    static <T> Iso<Box<T>, T> box() {
        return Iso.of(Box::content, Box::new);
    }
}

"@GenerateIsos: 'x' is not static"

The annotated method is an instance method. The generated field initialises itself with a static call, and there is no instance to make it on.

Fix. Make the method static.

record Point(int x) {}

final class PointIsos {

    @GenerateIsos
    Iso<Point, Integer> point() {
        return Iso.of(Point::x, Point::new);
    }
}

"@GenerateIsos: 'x' takes parameters"

The annotated method takes arguments. The generated field initialises itself by calling the method with none, and there is nothing for it to pass.

Fix. Take the arguments away, or drop @GenerateIsos and call the method directly.

record Point(int x) {}

final class PointIsos {

    @GenerateIsos
    static Iso<Point, Integer> point(int scale) {
        return Iso.of(Point::x, Point::new);
    }
}

"@GenerateIsos: 'x' does not return an Iso with both type arguments"

The method returns a void, a primitive, an array, a raw Iso, or something that is not an Iso at all. The generated field is typed from the two arguments of the returned Iso, and none of those carries them.

Fix. Return Iso<S, A> naming both, as Iso<Point, Tuple2<Integer, Integer>>.

final class PointIsos {

    @GenerateIsos
    static String point() {
        return "not an Iso";
    }
}

"@GenerateIsos: 'x' cannot be reached from 'p'"

The generated class lives in package p and calls the method from there, but the method, or a type enclosing it, is private, protected or package-private somewhere else. Most often seen with targetPackage.

Fix. Make the method and its enclosing types public, or generate into the package they are already visible from.

final class LengthIsos {

    @GenerateIsos(targetPackage = "com.example.optics")
    static Iso<String, Integer> length() {
        return Iso.of(String::length, "x"::repeat);
    }
}

"@GenerateFocus: record component 'X.y' has a wildcard type argument in Set<? extends T>"

A container that the processor widens through an optic instance is declared raw, or with a wildcard type argument. The same error covers Set, Collection, Map, Either, Try and every other such container, and is also reported as "has a raw Set".

Fix. Name the type argument, Set<Leaf> rather than Set<? extends Leaf>, or drop @GenerateFocus from the record and keep @GenerateLenses and @GenerateTraversals, which compose no optic instance and take the component as written. See Custom Containers.

@GenerateFocus
record Bag<T>(Set<? extends T> items) {}

"@GenerateTraversals: no traversal was generated for component 'X.y' of type Deque<T>" (a note)

@GenerateTraversals asks the TraversableGenerator SPI for each record component, and no generator on the annotation processor path claimed this one.

Fix. Declare the component as a container a generator supports: List, Set, Collection, Map, Optional, an array, or a type one of the generator plugins covers. For a raw container, give it its element type. For a third-party type, put a TraversableGenerator for it on the annotation processor path. A mixed record, one supported container beside one unsupported, keeps the traversals it can have and carries the note for the one it cannot; the note is the reminder, not a gate. A record that wants no traversal for any of its components should not carry @GenerateTraversals at all; @GenerateLenses on its own still gives every component a lens.

@GenerateTraversals
record Pending(Deque<String> queue) {}

"Multiple TraversableGenerator SPI providers with equal priority (N) support type X" (a warning)

Two generators on the annotation processor path both claim the type, and neither outranks the other: supports() answers true from both at the same priority().

Fix. Rank one of the providers: return PRIORITY_OVERRIDE from the one that should win, or PRIORITY_FALLBACK from the one that should yield, or drop one from the annotation processor path. The message names both provider classes. A consuming build running javac with -Werror turns the warning into an error, so the ranking is the remedy, not optional tidiness. See How Plugin Discovery Works.

"@TraverseField: the annotation on record component 'X.y' is not applied" (a note)

@TraverseField names a Traverse for a Kind<F, A> component with a declared witness, and this component is not one.

Fix. Declare the component as the Kind<F, A> the Traverse is written for, Kind<TreeKind.Witness, Tree> for a Traverse<TreeKind.Witness>, with both type arguments given and a witness that is a type rather than a bare or ? super wildcard, a type variable of the record, or a wildcard bounded by one; or drop the annotation and take the path the component gets on its own, applying traverseOver yourself where the witness is known. See Custom Kind Types with @TraverseField.

@GenerateFocus
record Inbox(
    @TraverseField(traverse = "org.higherkindedj.hkt.list.ListTraverse.INSTANCE")
        List<String> messages) {}

"@GenerateFocus: record component 'X.y' names a witness the processor does not recognise" (a note)

The component is a Kind<F, A> whose witness is one of Higher-Kinded-J's own, but not one the Focus processor has a Traverse registered for. Nothing widens it, so the generated method is a plain FocusPath focusing the Kind.

Fix. Add @TraverseField naming the Traverse instance for the witness, or keep the plain path and apply traverseOver yourself. See Kind Field Support.

@GenerateFocus
record Batch(Kind<NonEmptyListKind.Witness, String> items) {}

@ImportOptics and OpticsSpec interfaces

"@ImportOptics: Lens method 'x' carries no copy strategy annotation"

A method on an OpticsSpec interface returns Lens<S, A> but carries none of @Wither, @ViaConstructor, @ViaCopyAndSet or @ViaBuilder, so the processor has no way to know how the external type rebuilds itself.

Fix. Add the appropriate hint based on how the source type is copied. See Optics for External Types and Database Records with JOOQ for the full strategy table.

final class Session {

    public String user() {
        return "";
    }
}

@ImportOptics
interface SessionOpticsSpec extends OpticsSpec<Session> {

    Lens<Session, String> user();
}

"'XOpticsSpec.foo' is a default method"

A spec interface declares a default method. A method body cannot be read during annotation processing, so there is nothing for the generated class to carry.

Fix. Keep the spec interface to annotated abstract methods. Composed optics belong in a static method on the interface, or in an ordinary utility class; either one calls the generated statics by name, for example JsonNodeOptics.object().andThen(...).

final class Session {

    public String user() {
        return "";
    }
}

@ImportOptics
interface SessionOpticsSpec extends OpticsSpec<Session> {

    default Lens<Session, String> user() {
        return Lens.of(Session::user, (session, user) -> session);
    }
}

"'XOpticsSpec' declares OpticsSpec<S>, which is a type variable"

The spec interface is generic, and its own type parameter is the source type: interface BoxOpticsSpec<S extends Box> extends OpticsSpec<S>.

Fix. Name the type the optics are for as the type argument, with its own type arguments where it has any: OpticsSpec<Box>. Where the bound names a single type that is not raw, the message suggests it for you. A source type that is itself generic is supported, and the spec names its own type parameters: interface BoxOpticsSpec<U> extends OpticsSpec<Box<U>> generates static <U> Lens<Box<U>, String> label(). See Spec Interfaces for which parameters a generated method declares. It is only a bare type variable, standing for the whole source type, that has no source to read.

class Session {}

@ImportOptics
interface SessionOpticsSpec<S extends Session> extends OpticsSpec<S> {

    @Wither("withUser")
    Lens<S, String> user();
}

"'XOpticsSpec' declares OpticsSpec<Box>, which names the raw type 'Box'"

The source type names a generic type without its arguments.

Fix. Name the raw type's arguments in the OpticsSpec clause: OpticsSpec<Box<String>>, OpticsSpec<Outer<String>.Holder>, OpticsSpec<Box<List<String>>>. A spec whose optics should stay generic declares its own type parameters and passes them on, interface BoxOpticsSpec<U> extends OpticsSpec<Box<U>>, as above. See Spec Interfaces.

record Box<T>(T content) {

    Box<T> withContent(T content) {
        return new Box<>(content);
    }
}

@ImportOptics
interface BoxOpticsSpec extends OpticsSpec<Box> {

    @Wither("withContent")
    Lens<Box, String> content();
}

"@ThroughField: '...' reaches field 'items', which is declared as ArrayList<String> rather than as the List interface"

The spec's own lens for the field focuses something narrower than a container interface: a concrete container such as ArrayList, or another interface such as Deque. Auto-detection matches List, Set, Collection, Map, Optional and reference-type arrays, on the interface itself.

Fix. Name a traversal that rebuilds the declared type, Traversals.forIterableCollecting(ArrayList::new) for a list-shaped container or Traversals.forMapValuesCollecting(TreeMap::new) for a map, exposed as a static method and named fully qualified: @ThroughField(field = "items", traversal = "com.example.MyTraversals.forArrayList()"). Where the type is yours, declaring the field as the interface (List<String>) is the simpler route. See @ThroughField auto-detection.

final class Shelf {

    public ArrayList<String> items() {
        return new ArrayList<>();
    }

    public Shelf withItems(ArrayList<String> items) {
        return this;
    }
}

@ImportOptics
interface ShelfOpticsSpec extends OpticsSpec<Shelf> {

    @Wither("withItems")
    Lens<Shelf, ArrayList<String>> items();

    @ThroughField(field = "items")
    Traversal<Shelf, String> eachItem();
}

"@ThroughField: '...' composes through a lens named 'items', which the spec does not declare"

A @ThroughField traversal is generated as the spec's own lens for the field composed with the container traversal, Spec.items().andThen(...). The spec has to declare that Lens<S, F> items() alongside it, with its copy strategy, and this one does not. Without the lens the generated file could only fail with cannot find symbol, so the processor refuses the declaration instead.

Fix. Declare the lens method for the field on the spec, or use @TraverseWith to name a traversal over the source type that stands on its own.

final class Shelf {

    public List<String> items() {
        return List.of();
    }
}

@ImportOptics
interface ShelfOpticsSpec extends OpticsSpec<Shelf> {

    @ThroughField(field = "items")
    Traversal<Shelf, String> eachItem();
}

"@ThroughField: '...' declares focus 'Integer' over field 'items' of type List<String>, whose elements the standard traversal hands back as 'String'"

The method's declared focus does not contain what the auto-detected traversal hands back. That is the container's elements, a Map's values, an Optional's element, or Object where the element sits behind a super- or unbounded wildcard.

Fix. Declare the focus as the type the message names, or name a traversal of your own with @ThroughField(field = "items", traversal = "..."), which is the author's undertaking that it rebuilds the declared shape.

final class Shelf {

    public List<String> items() {
        return List.of();
    }

    public Shelf withItems(List<String> items) {
        return this;
    }
}

@ImportOptics
interface ShelfOpticsSpec extends OpticsSpec<Shelf> {

    @Wither("withItems")
    Lens<Shelf, List<String>> items();

    @ThroughField(field = "items")
    Traversal<Shelf, Integer> eachItem();
}

"@InstanceOf target 'com.example.Foo' is not a subtype of source type 'com.example.Base'"

The class passed to @InstanceOf(SubType.class) is not a subclass of the optic's source type.

Fix. Verify that SubType extends or implements the spec's <S> parameter. If you are working with sum types that don't use a sealed hierarchy (such as Jackson's pre-3.x JsonNode), use @MatchWhen with predicate and getter method names instead.

sealed interface Payment permits Card, Cash {}

record Card(String number) implements Payment {}

record Cash(int pence) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    @InstanceOf(String.class)
    Prism<Payment, String> text();
}

"@InstanceOf: '...' declares its focus as Circle<T>, which the test cannot narrow to"

The prism promises a type argument the test cannot check.

Fix. Declare the focus as Circle<?>, which is what the test earns, or narrow through a predicate and getter of the source type with @MatchWhen, which reads the argument off the source rather than inventing it. Where the source type does carry the argument, as in a Circle<X> implements Shape<X> reached from Shape<T>, the prism may promise it and the generated test names it. See Spec Interfaces.

class Shape {}

class Circle<X> extends Shape {}

@ImportOptics
interface ShapeOpticsSpec<T> extends OpticsSpec<Shape> {

    @InstanceOf(Circle.class)
    Prism<Shape, Circle<T>> circle();
}

"@InstanceOf: '...' names '...', which carries type parameters of its own and is a member of a generic type"

The test has to name the type it checks, and an instanceof cannot write Outer<X>.Inner<Y>. Naming Inner's type arguments would mean naming the enclosing type's as well, which instanceof does not allow.

Fix. Declare the member static, so it can be named on its own, or narrow through a predicate and getter with @MatchWhen.

class Node<U> {}

class Outer<X> {

    class Inner<Y> extends Node<Y> {}
}

@ImportOptics
interface NodeOpticsSpec<U> extends OpticsSpec<Node<U>> {

    @InstanceOf(Outer.Inner.class)
    Prism<Node<U>, Outer<?>.Inner<U>> inner();
}

"@InstanceOf: '...' narrows to '...', which is not a '...'"

The class the annotation names is not one the prism's focus type accepts.

Fix. Name the class the focus declares, or declare the focus as a supertype of the narrowed type. A prism whose focus is deliberately wider than the test is fine, as in @InstanceOf(ArrayList.class) Prism<Collection<T>, List<T>>; it is only a focus the narrowed value cannot be assigned to that is rejected.

sealed interface Payment permits Card, Cash {}

record Card(String number) implements Payment {}

record Cash(int pence) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    @InstanceOf(Card.class)
    Prism<Payment, Cash> card();
}

"@ViaCopyAndSet: copyConstructor names '...', which does not resolve to a type"

copyConstructor is a plain string, resolved as a fully qualified class name only: it is not read against the spec interface's imports, and it takes no type arguments.

Fix. Give the class's fully qualified name (com.example.BaseConfig; a nested class is com.example.Outer.Base), the class alone without type arguments, since the processor supplies those from the source type's own extends clause. Drop the attribute to pass the source unchanged.

// Endpoint is the legacy type from the copy-strategies page: two copy constructors,
// taking BaseEndpoint and Audited, and a setHost setter.
@ImportOptics
interface EndpointOpticsSpec extends OpticsSpec<Endpoint> {

    @ViaCopyAndSet(copyConstructor = "com.example.MissingBase", setter = "setHost")
    Lens<Endpoint, String> host();
}

"@ViaCopyAndSet: copyConstructor names '...', which 'S' does not extend or implement"

The generated setter passes the source to the copy constructor as (ParameterType) source, so only a supertype of S can be named there.

Fix. Name a class or interface S extends or implements, or drop the attribute.

@ImportOptics
interface EndpointOpticsSpec extends OpticsSpec<Endpoint> {

    @ViaCopyAndSet(copyConstructor = "java.lang.Thread", setter = "setHost")
    Lens<Endpoint, String> host();
}

"@ViaCopyAndSet: copyConstructor names '...', which is not public and so cannot be named from '...'"

The generated optics class has to write the cast, so it has to be able to name the type. A package-private supertype is invisible from the package the optics class is generated into, even though new S(source), which never names it, would have compiled.

Fix. Name a public supertype, generate into that package with @ImportOptics(targetPackage = ...), or drop the attribute.

"@ViaCopyAndSet: copyConstructor names '...', which '...' reaches as '...', and no constructor accepts"

The name is a genuine supertype, but no single-argument constructor of S takes the type S actually reaches it as. java.lang.Object and marker interfaces such as Serializable reach this often.

Fix. Name a supertype of S that one of the listed constructors takes, as the class alone without type arguments, or drop the attribute. The list carries type arguments and the attribute does not, so read it to recognise your supertype in it rather than to copy from it, and a listed type that is not a supertype of S cannot be named at all. The attribute is only needed when the copy constructor is overloaded; see Copy Strategies.

@ImportOptics
interface EndpointOpticsSpec extends OpticsSpec<Endpoint> {

    @ViaCopyAndSet(copyConstructor = "java.lang.Object", setter = "setHost")
    Lens<Endpoint, String> host();
}

"@ViaCopyAndSet: '...' is written with a wildcard type argument"

The source type carries a wildcard, OpticsSpec<Node<?>>, and the strategy rebuilds it through a constructor.

Fix. Name the type the wildcard stands for, or switch to @Wither, which rebuilds through a method and names no constructor, so a wildcard source type is no obstacle there.

final class Slot<T> {

    private String label = "";

    Slot() {}

    Slot(Slot<T> other) {
        this.label = other.label;
    }

    public String label() {
        return label;
    }

    public void setLabel(String label) {
        this.label = label;
    }
}

@ImportOptics
interface SlotOpticsSpec extends OpticsSpec<Slot<?>> {

    @ViaCopyAndSet(setter = "setLabel")
    Lens<Slot<?>, String> label();
}

"@ImportOptics: '...' focuses '...', which is not a '...'"

A prism runs both ways, and the generated one builds back with identity: it returns the value it narrowed.

Fix. Focus the variant that carries the value, TextNode rather than String, and read the payload with a further optic. Where the value type is the point, write that prism by hand with Prism.of and a build side that constructs the source, such as TextNode::valueOf.

sealed interface Payment permits Card, Cash {

    default boolean isCard() {
        return this instanceof Card;
    }

    default String number() {
        return "";
    }
}

record Card(String number) implements Payment {}

record Cash(int pence) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    @MatchWhen(predicate = "isCard", getter = "number")
    Prism<Payment, String> number();
}

"cannot find symbol", inside the generated XPrisms.java, after using @MatchWhen

The processor does not validate the strings in @MatchWhen(predicate = "isFoo", getter = "asFoo"). It splices them into the generated source verbatim, so a typo surfaces as an ordinary javac error inside generated code rather than as a processor message.

Fix. Check the names against the source type's API. Both methods must take no arguments; the predicate returns boolean and the getter returns the prism's target type.

sealed interface Payment permits Card, Cash {}

record Card(String number) implements Payment {}

record Cash(int pence) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    @MatchWhen(predicate = "isCrad", getter = "asCard")
    Prism<Payment, Card> card();
}

"Prism method 'x' requires a prism hint annotation: @InstanceOf or @MatchWhen"

A spec-interface method returning Prism<S, A> with neither hint.

Fix. Add @InstanceOf for a real subtype, or @MatchWhen for a check-and-extract API. The same rule applies to traversals: "Traversal method 'x' requires a traversal hint annotation: @TraverseWith or @ThroughField".

sealed interface Payment permits Card, Cash {}

record Card(String number) implements Payment {}

record Cash(int pence) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    Prism<Payment, Card> card();
}

@GeneratePathBridge and @PathVia

Every message on this page is quoted as the processor emits it, with 'x' standing in for the name it prints.

The bridge is a file you never wrote and cannot edit, so the errors below refuse a shape at your own declaration rather than emitting source that would fail, or warn, in the build that consumes it. The last entry is a warning rather than an error: the bridge it describes is written, it just has nothing in it.

"@PathVia: the return type of 'x' is 'Y', which no Path wraps"

The method returns a type the bridge has no Path for. The bridged set is Optional, Maybe, Either, Try, Validated and IO; CompletableFuture is the type most often met outside it.

Fix. Return one of the six, or drop @PathVia and wrap the call by hand.

@GeneratePathBridge
interface Orders {

    @PathVia
    CompletableFuture<String> find(String id);
}

"@PathVia: the signature of 'x' names the raw type 'Y'"

A generic type is written without its arguments somewhere the bridge copies verbatim: Optional as the return type, Optional<List> as its argument, List as a parameter. Each becomes a [rawtypes] warning in the generated file, and the @SuppressWarnings on your own declaration does not cover a file it does not appear in.

Fix. Name the type arguments: Optional<Item> rather than Optional.

@GeneratePathBridge
interface Orders {

    @PathVia
    Optional find(String id);
}

"@PathVia: the error type of the 'Validated' returned by 'x' is the wildcard '?'"

A Validated bridge names its error type twice: in the ValidationPath it returns, and in the Semigroup it asks the caller for.

Fix. Name the error type.

@GeneratePathBridge
interface Orders {

    @PathVia
    Validated<?, String> find(String id);
}

"@PathVia: the type parameter 'T' on 'x' has the same name as 'Y's"

The bridge declares the interface's type parameters and the method's side by side, which the delegate never does; where the names collide, the method's hides the interface's.

Fix. Rename the method's type parameter.

interface Narrower<U> {

    @PathVia
    <T extends U> Optional<T> narrow(T candidate);
}

@GeneratePathBridge
interface TextNarrower<T> extends Narrower<T> {}

"@PathVia: the bridge cannot call 'x'"

The method is static or private. The bridge reaches its delegate through an interface reference, which gets at abstract and default members and nothing else.

Fix. Make it an abstract or default instance method, or drop @PathVia from it.

@GeneratePathBridge
interface Orders {

    @PathVia
    static Optional<String> find(String id) {
        return Optional.empty();
    }
}

"@PathVia: the bridge signature for 'x' is already taken"

Two @PathVia methods land on the same generated name and parameter types, usually through @PathVia(name = ...). One class cannot declare both.

Fix. Give one of them a distinct name, or drop @PathVia from it.

@GeneratePathBridge
interface Orders {

    @PathVia
    Optional<String> find(String id);

    @PathVia(name = "find")
    Optional<String> lookup(String id);
}

"@PathVia: @PathVia(name = "...") is not a method name"

The name attribute is not a Java identifier, or it is a keyword. The bridge declares a method called exactly that.

Fix. Give a plain identifier, or drop the attribute to keep the delegate's own name.

@GeneratePathBridge
interface Orders {

    @PathVia(name = "find-order")
    Optional<String> find(String id);
}

"@GeneratePathBridge: on 'X', the signature names 'Y', which cannot be reached from 'p'"

targetPackage puts the bridge in package p, and something the bridge writes down, a parameter type, a return type, a bound or the delegate itself, is not visible there. The same message names the bound on 'T' when the culprit is a type parameter's bound.

Fix. Make the type public, or drop targetPackage so the bridge is written beside the interface.

class Secret {}

@GeneratePathBridge(targetPackage = "com.example.paths")
interface Vault {

    @PathVia
    Optional<Secret> find(String id);
}

"@GeneratePathBridge: no @PathVia method was found among 'X's members" (a warning)

No @PathVia method survives among the interface's members, so the bridge is written with a constructor and nothing else.

Fix. Put @PathVia on the methods to bridge, or drop @GeneratePathBridge.

@GeneratePathBridge
interface Orders {

    Optional<String> find(String id);
}

Focus DSL chains

traverseOver and the higher-kinded witness type

traverseOver is generic in the higher-kinded witness type.

Fix. State the type parameters explicitly when the witness is not obvious from context:

TraversalPath<User, Role> allRoles =
    rolesPath.<ListKind.Witness, Role>traverseOver(ListTraverse.INSTANCE);

"Incompatible types when chaining .each().via()"

Usually one .each() too many.

Fix. Drop the extra .each(), and break long chains into intermediate variables so each carries a concrete type:

TraversalPath<Company, Department> depts     = CompanyFocus.departments();
TraversalPath<Company, Employee>   employees = depts.via(DepartmentFocus.employees());
TraversalPath<Company, Integer>    salaries  = employees.via(EmployeeFocus.salary());

"Cannot infer type argument(s)" on an intermediate .each()

Only the final each() in a chain can infer its element type from the target type. An intermediate one has nothing to infer from.

Fix. Spell the element type at the intermediate hop:

TraversalPath<Company, Integer> allSalaries =
    FocusPath.of(CompanyLenses.departments())
        .<Department>each()
        .via(DepartmentLenses.employees())
        .<Employee>each()
        .via(EmployeeLenses.salary());

"Method reference ::new doesn't work with single-field records as BiFunction"

A single-component record has no two-argument constructor, and Lens.of's setter is a BiFunction<S, A, S> taking (source, newValue). It is an arity mismatch, not an inference wobble.

Fix. Use an explicit lambda:

Lens<Outer, Inner> lens = Lens.of(Outer::inner, (o, i) -> new Outer(i));

"Sealed or non-sealed local classes are not allowed"

Defining a sealed interface inside a method body. Java does not permit this regardless of HKJ.

Fix. Hoist the sealed interface to class or top level.

Free Monad DSL programs

"Cannot resolve method 'flatMap(Function<...>)'"

The Free<F, A> value's witness type does not match what the surrounding interpreter expects, or you are mixing Free<OpticOpKind.Witness, ...> with another Free instance.

Fix. Confirm that every step in the program uses the same OpticPrograms factory methods, and that interpreter calls are paired with the matching witness.

"Type mismatch: Free<F, A> cannot be converted to A"

Forgetting to call an interpreter. A Free program is data; you must run it to get a result.

Fix. Pass the program to an interpreter:

Person result = OpticInterpreters.direct().run(program);

When the message does not match anything here

1. Is the project rebuilt from clean? Many "cannot find symbol" errors clear after ./gradlew clean build.
2. Is the annotation processor on the classpath? See Build Plugins for the canonical setup.
3. Is the IDE indexing the generated sources directory? Refresh the project after a build.
4. If it is none of these, please file an issue at the Higher-Kinded-J GitHub repository with the minimal reproducer and the full error.

Previous: Conversions Next: Production Readiness