Common Compiler Errors

Find the message your compiler printed, then read what it means and how to fix it.

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 Find your message 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
    accTitle: Where a compiler message came from
    accDescr: Your declaration goes to the processor first, and a refusal there is reported at your declaration, which is most of this page. An accepted declaration becomes a generated file; javac refusing that file reports cannot find symbol inside a class you did not write. If javac refuses your call site instead, the message is a Focus DSL chain or Free Monad error; otherwise the build succeeds.
    D["Your declaration:<br/>@Generate*, or<br/>a spec interface"]
    P{"Does the processor<br/>accept it?"}
    R["Refused at your<br/>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<br/>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. With @ImportOptics, the class is also missing when a type it imports never appeared: the import waits for a type another processor writes, and javac reports that type as missing too. An error reported earlier, or a warning under -Werror, stops annotation processing before a waiting import is read, so fix those first.

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 Voucher {}

"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 {}

"@GeneratePrisms: 'Pair' declares [B], which 'Shape' does not bind"

A permitted subtype needs a type parameter that its implements clause leaves free. @ImportOptics reports the same for an imported sealed interface. The message takes one of two forms:

Fix. Bind the free parameter in the clause, as the message shows, giving the sealed interface a type parameter for it if it has none to spare. Where you cannot change the clause, as for a sealed interface from a library, write the prism by hand with Prism.of.

@GeneratePrisms
sealed interface Shape<T> permits Pair {}

record Pair<A, B>(A a, B b) implements Shape<A> {}

class Shapes<X> {

    @GeneratePrisms
    sealed interface Shape<T> permits Shapes.Hexagon {}

    final class Hexagon<Y extends X> implements Shape<Y> {}
}

"@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 value) {}

final class BoxIsos {

    @GenerateIsos
    static <T> Iso<Box<T>, T> box() {
        return Iso.of(Box::value, 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 Quantity(int units) {}

final class QuantityIsos {

    @GenerateIsos
    Iso<Quantity, Integer> quantity() {
        return Iso.of(Quantity::units, Quantity::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 Quantity(int units) {}

final class QuantityIsos {

    @GenerateIsos
    static Iso<Quantity, Integer> quantity(int scale) {
        return Iso.of(Quantity::units, Quantity::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);
    }
}

"@GenerateLenses: record component 'x' of 'X' names 'Y', which cannot be reached from 'p'"

A type the generated companion names is hidden from the package the companion is written into: it, or a class enclosing it, is private, or it comes from another package and is not public. @GenerateLenses and the other optics generators, @ImportOptics, @GenerateAssembly, @GenerateErrorEnvelope, @EffectAlgebra and @PathSource refuse such a type at the annotation. The message names where the companion meets the type: the annotated type itself (record 'Shop.Item' cannot be reached from 'p'), or a component, subtype, bound, field, optic, variant, operation, witness or error type.

Fix. Remove private from the class the message names. From another package, make it public; under targetPackage, removing targetPackage also works for a type beside the annotated one, and the message offers it where it does.

@GenerateLenses: record component 'sku' of 'Item' names 'Sku', which cannot be reached from
'com.example'. The generated companion is a top-level class in that package, where it names
every type it reads or writes, so each has to be visible from there. Remove 'private' from 'Sku'.

class Shop {
    private record Sku(String value) {}

    @GenerateLenses
    record Item(Sku sku) {}
}

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

A container that the processor widens through the optic its SPI generator supplies is declared raw, or with a wildcard type argument. The same error covers Either, Try, Validated, Map and every other such container, and is also reported as "has a raw Either". A Map or another collection draws it only once something widens it. The five built-in containers, Optional, Maybe, List, Set and Collection, never draw it.

Fix. Name the type arguments, Either<String, Widget> rather than Either<String, ? extends Widget>. For a wildcard, you can instead drop @GenerateFocus from the record and keep @GenerateLenses and @GenerateTraversals, which compose no optic instance. The lens keeps the component's type as written. The traversal focuses the type the wildcard stands for: Widget for ? extends Widget, and Object for ? or ? super Widget. A raw container has no element type for @GenerateTraversals to focus, so it draws a note and no traversal there; keep @GenerateLenses alone for one. See Custom Containers.

@GenerateFocus
record Bag<T>(Either<String, ? extends T> item) {}

"@GenerateFocus: the navigator for 'X.y' cannot navigate to 'T.z'"

X writes generateNavigators = true, its field y holds another @GenerateFocus record, T, and T has a field named like one of the path's own methods that take no arguments. On a FocusPath those are last, head, tail, init, each, some, nullable, cons, snoc, headTail, initLast, segments, pathString, toLens, asAffine, asTraversal, asFold and toPath. An AffinePath and a TraversalPath differ a little, and the processor reads each list from the class the navigator extends.

Fix. Rename the field, or keep y a plain path, as the message says. It names the change that does that on X: add y to excludeFields, remove it from includeFields, or, where includeFields names only y, remove includeFields and set generateNavigators = false. A plain path still reaches the clashing field through .via(TFocus.z()).

@GenerateFocus
record FullName(String first, String last) {}

@GenerateFocus(generateNavigators = true)
record Signatory(FullName name) {}

error: @GenerateFocus: the navigator for 'Signatory.name' cannot navigate to 'FullName.last'. A navigator is a FocusPath, which has its own last(), so SignatoryFocus.name().last() would call that method instead of navigating to the field. Rename 'FullName.last', or add excludeFields = "name" to @GenerateFocus on Signatory to keep 'name' a plain path.

"@GenerateFocus: record component 'X.y' has no navigator into T" (a note)

X leaves navigators to the default, and the record y holds, T, has a field named like one of the path's own methods that take no arguments, the ones the entry before lists. A navigator could not navigate to that field, so y gets none, and its method keeps the path it has without one.

Fix. Rename the field to give y a navigator. To keep the plain path and silence the note, add y to excludeFields on X, as the note says.

@GenerateFocus
record FullName(String first, String last) {}

@GenerateFocus
record Signatory(FullName name) {}

Note: @GenerateFocus: record component 'Signatory.name' has no navigator into FullName. A navigator is a FocusPath, which has its own last(), so it cannot navigate to 'FullName.last', and SignatoryFocus.name() keeps the path it has without one. Rename 'FullName.last' to navigate into FullName, or add excludeFields = "name" to @GenerateFocus on Signatory to keep the path without this note.

"@GenerateFocus: record component 'X.y' has no navigator over its T elements" (a note)

X writes generateNavigators = true, and y is a Map, an array or a third-party collection of @GenerateFocus records that X does not widen, or a container holding one, such as List<Map<String, Item>>. A navigator steps into a container only where the record widens it, so y's method keeps a path to the whole container. If includeFields names y, it draws the includeFields warning instead. Where T has a field named like a method of the widened path, such as last, the note names that field too, since widening y alone would draw the cannot-navigate error.

Fix. Add y to widenFields on X, as the note says, and the method returns a navigator over the elements. Where the note names a field of T, rename it first, or add y to excludeFields to keep the container whole. widenCollections = true widens every such container instead. To keep the container whole otherwise, drop generateNavigators = true, which is the default, and the note goes with it. Whichever you choose, find each call through a field the note names, such as byTicker().last(), by hand: it compiles against the path's own last(), so the compiler cannot point at it.

@GenerateFocus
record Bottle(String label, int volume) {}

@GenerateFocus(generateNavigators = true)
record Hamper(Bottle[] bottles) {}

Note: @GenerateFocus: record component 'Hamper.bottles' has no navigator over its Bottle elements. A navigator steps into a container only where the record widens it, and Hamper does not widen 'bottles'. Add widenFields = "bottles" to @GenerateFocus on Hamper to navigate into its elements.

@GenerateFocus
record Quote(String ticker, double last) {}

@GenerateFocus(generateNavigators = true)
record Book(Map<String, Quote> byTicker) {}

Note: @GenerateFocus: record component 'Book.byTicker' has no navigator over its Quote elements. A navigator steps into a container only where the record widens it, and Book does not widen 'byTicker'. Widened, its navigator would be a TraversalPath, which has its own last(), so it could not navigate to 'Quote.last'. Rename 'Quote.last', then add widenFields = "byTicker" to @GenerateFocus on Book to navigate into its elements, or add excludeFields = "byTicker" to @GenerateFocus on Book to go without this note.

"@GenerateFocus: the navigator for 'X.y' has no TraversalForm" (a note)

X writes generateNavigators = true, and its field y holds another @GenerateFocus record, T. T has a field named like a no-argument method that only a wider path has: headOption or toTraversal on a TraversalPath, or toAffine on an AffinePath. y keeps its own navigator, but not its form for that path, so a hop into y from such a path returns the plain path. The note names AffineForm where that is the form left out. It goes to X, which declares y, since the form belongs to y's navigator; a record whose hop into y returns the plain path is not told.

Fix. Rename the field of T, as the note says, and the navigator gets its form. To keep the name and go without the form, drop generateNavigators = true from X, since it is the default, and the note goes with it.

@GenerateFocus
record Feed(String name, String headOption) {}

@GenerateFocus(generateNavigators = true)
record Channel(Feed feed) {}

Note: @GenerateFocus: the navigator for 'Channel.feed' has no TraversalForm. A TraversalForm would be a TraversalPath, which has its own headOption(), so it could not navigate to 'Feed.headOption', and a hop into 'feed' from a TraversalPath returns a plain TraversalPath. Rename 'Feed.headOption' to give the navigator for 'feed' a TraversalForm, or remove generateNavigators = true from @GenerateFocus on Channel to go without this note.

"@GenerateFocus: includeFields on X names "y", which is not a component of X"

includeFields, excludeFields or widenFields names a field the record does not have: a typo, or a name a rename left behind. In includeFields it costs the most, since a non-empty list gives navigators only to the fields it names, so a list whose only name is a typo leaves every field without one.

Fix. Write the component's name. Where one is close, the message offers it: a near misspelling, a different case such as "Positions", or an accessor spelling such as "getAddress". Take out a name that is no longer wanted.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "kisok")
record Hawker(String name, Kiosk kiosk) {}

error: @GenerateFocus: includeFields on Hawker names "kisok", which is not a component of Hawker. includeFields gives navigators only to the components it names, so a name that matches none gives no component a navigator. Did you mean 'kiosk'? Found on Hawker: [name, kiosk]. Replace "kisok" with "kiosk" in includeFields on Hawker.

"@GenerateFocus: includeFields on X names "y", whose field cannot have a navigator" (a warning)

The name matches a component, but that component cannot return a navigator. A String, a List<String> and a record without @GenerateFocus have no navigator target. A List, Set, Collection, Optional or Maybe of @GenerateFocus records has one, as do such containers nested in one another and a Kind the processor traverses. A Map, an array of records or another supported container has one only where the declaring record widens it.

Fix. Name a field that can return a navigator, from those the warning lists. For an unannotated record, annotate its type with @GenerateFocus. For an unwidened container, add the field to widenFields. Where no field can navigate, remove includeFields and set generateNavigators = false. Follow the warning's fix line: leaving includeFields in place with navigators off draws a different warning.

A non-empty includeFields gives navigators only to the fields it names, so naming an ineligible field also takes navigators away from every eligible field it leaves out. The warning points at the offending name and stops a -Werror build. A field already explained by a target note or error gets no additional warning. The unwidened-container note becomes this warning when includeFields names the field.

• An unwidened Map<String, Box<?>>, with Box<T> annotated, is offered widenFields to step into its Box elements. That alone gives no navigator: the existing wildcard-target note then offers a concrete Box<Object>.
• A Map<String, ? extends Kiosk> holds Kiosk records, but its wildcard prevents widening. Write Map<String, Kiosk> and add the field to widenFields, as the warning says.
• A List, Optional or other container the method steps into, holding a record without @GenerateFocus, is offered the annotation, as a field of that record is.
• When several entries need a replacement, the first in list order receives it and the rest are offered removal. If another entry has a navigator or a correction of its own, remove the invalid name instead. Following all fix lines leaves one list without duplicate names.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "id")
record Hawker(String id, Kiosk kiosk) {}

warning: @GenerateFocus: includeFields on Hawker names "id", whose field cannot have a navigator. Navigator generation cannot reach a @GenerateFocus record through String. It needs a @GenerateFocus record or a supported container of one. Replace "id" in includeFields on Hawker with a navigator field from [kiosk].

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "kiosk")
record Hawker(String id, Kiosk kiosk) {}

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "sites")
record Hawker(java.util.Map<String, Kiosk> sites) {}

warning: @GenerateFocus: includeFields on Hawker names "sites", whose field cannot have a navigator. A navigator steps into a container only where the record widens it, and Hawker does not widen "sites". Add widenFields = "sites" to @GenerateFocus on Hawker.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "sites")
record Hawker(java.util.Map<String, ? extends Kiosk> sites, Kiosk kiosk) {}

warning: @GenerateFocus: includeFields on Hawker names "sites", whose field cannot have a navigator. Map<String, ? extends Kiosk> holds Kiosk records, but its wildcard type arguments prevent widening as written. Write Map<String, Kiosk> in place of Map<String, ? extends Kiosk> and add widenFields = "sites" to @GenerateFocus on Hawker.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "sites", widenFields = "sites")
record Hawker(java.util.Map<String, Kiosk> sites, Kiosk kiosk) {}

var towns = HawkerFocus.sites().town();

record Kiosk(String town) {}

@GenerateFocus(includeFields = "sites")
record Hawker(java.util.List<Kiosk> sites) {}

warning: @GenerateFocus: includeFields on Hawker names "sites", whose field cannot have a navigator. Kiosk is a record without @GenerateFocus. Navigator generation cannot reach a @GenerateFocus record through List<Kiosk>. It needs a @GenerateFocus record or a supported container of one. Remove includeFields and set generateNavigators = false in @GenerateFocus on Hawker. Alternatively, annotate record Kiosk with @GenerateFocus.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "sites")
record Hawker(java.util.List<Kiosk> sites) {}

var towns = HawkerFocus.sites().town();

"@GenerateFocus: ... on X changes nothing, because ..." (a warning)

A field list is set where the record's other settings never read it, so the generated class is the one you would get without it. There are three such pairs:

• excludeFields beside a non-empty includeFields, which alone decides which fields get navigators.
• includeFields or excludeFields with generateNavigators = false, where no field gets a navigator.
• widenFields beside widenCollections = true, which widens every field widenFields could name.

Fix. Remove the list, or the setting that leaves it unread, as the warning says. Either remedy compiles without the warning.

@GenerateFocus
record Kiosk(String town) {}

@GenerateFocus(includeFields = "home", excludeFields = "relief")
record Trader(String name, Kiosk home, Kiosk relief) {}

warning: @GenerateFocus: excludeFields on Trader changes nothing, because includeFields is set beside it. A non-empty includeFields gives navigators to the components it names and to no others, so excludeFields is never read. Remove excludeFields from @GenerateFocus on Trader, or remove includeFields to give navigators to every component but those excludeFields names.

"@GenerateFocus: widenFields on X names "y", whose T is widened without it" (a warning)

widenFields names a field whose path it cannot change. Either the field's method widens its container anyway, as it does a List, an Optional or an Either, or the field holds no container widenFields widens, such as a String or an int[]. The second reads "which holds no container widenFields widens".

Fix. Take the name out of widenFields, as the warning says. widenFields is for a Map, an array of objects or a third-party collection, which a method otherwise leaves whole. A third-party collection needs a TraversableGenerator on the annotation processor path, such as those hkj-processor-plugins provides, and without one it holds no container widenFields widens; the warning offers that remedy too.

@GenerateFocus(widenFields = "tags")
record Stall(String name, List<String> tags) {}

warning: @GenerateFocus: widenFields on Stall names "tags", whose List<String> is widened without it. StallFocus.tags() returns a TraversalPath whether widenFields names it or not. Remove widenFields from @GenerateFocus on Stall.

"@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 Backlog(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, widening it yourself with each(EachInstances.fromTraverse(traverse)) 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 widen it yourself with each(EachInstances.fromTraverse(traverse)). See Kind Field Support.

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

@ImportOptics and OpticsSpec interfaces

"@ImportOptics: '...' lists no classes to import, so nothing is generated" (a warning)

An @ImportOptics on a package-info.java, or on a class or interface that does not reach OpticsSpec, names no class to import, so it generates nothing.

Fix. List the classes to import, as @ImportOptics({Order.class}), or remove the annotation. On an interface you meant as a spec, extend OpticsSpec<S> for the type its optics are for.

@ImportOptics
class OrderImports {}

"@ImportOptics: '....class' names a primitive type, which has no optics to import"

The class list holds a literal for a primitive type, an array type or void, such as int.class or String[].class. Optics are generated from the declaration of a class, interface, record or enum, and these have none. An array reads names an array type, and void.class reads names void.

Fix. Remove the literal from the list.

@ImportOptics({int.class})
class CountImports {}

"@ImportOptics: '...' extends OpticsSpec<...> and also lists classes to import"

A spec interface also carries a class list. A spec generates the optics its own methods declare, for the type its OpticsSpec<S> names, and does not read a class list.

Fix. Move the class list to a package-info.java or to another class or interface, or remove it.

final class Session {

    public String user() {
        return "";
    }

    public Session withUser(String user) {
        return this;
    }
}

@ImportOptics({java.time.LocalDate.class})
interface SessionOpticsSpec extends OpticsSpec<Session> {

    @Wither(value = "withUser", getter = "user")
    Lens<Session, String> user();
}

"@ImportOptics: '...' extends OpticsSpec only through '...'"

An interface that lists no classes reaches OpticsSpec<S> through another interface rather than declaring it itself. Reading a spec that way is not supported yet.

Fix. Declare OpticsSpec<S> on the spec itself. Where the interface in between names the source type, the message gives the clause to add beside it, extends OpticsSpec<Session>, SessionBase. Where it does not, because it is raw or passes on a type parameter, name the source type in its place: extends OpticsSpec<Session>.

An interface that lists classes, and does not declare OpticsSpec<S> itself, imports them instead, whatever it extends.

final class Session {}

interface SessionBase extends OpticsSpec<Session> {}

@ImportOptics
interface SessionOpticsSpec extends SessionBase {}

"@ImportOptics: '...' implements OpticsSpec but is not an interface"

A class that lists no classes reaches OpticsSpec<S>, directly, through an interface or through a superclass. A spec is an interface: its abstract methods are the optics to generate, and the generated class stands in for it rather than extending it.

Fix. Declare the spec as an interface extending OpticsSpec<S> in place of the class. The message names the clause where it can: Declare it as an interface extending OpticsSpec<Session>.

final class Session {}

@ImportOptics
abstract class SessionOpticsSpec implements OpticsSpec<Session> {}

"@ImportOptics: '...' inherits the optic method '...' from '...'"

A spec interface inherits a method that returns an optic, abstract or default, from another interface. A spec generates optics from the methods it declares itself, and reading them from another interface is not supported yet, so the generated class would be missing that optic.

Fix. Declare the method on the spec itself, annotated as it is on the interface it comes from. The message writes the signature for the spec's own source type, Lens<Order, UUID> id() for a mix-in's Lens<S, UUID> id(); reached through a raw clause, it asks for the type arguments instead. For a default method, redeclare it on the spec as an abstract method with its copy strategy or hint annotation, which replaces the inherited one. Or move the default out of the mix-in into a static method that calls the generated statics. A method the spec redeclares is its own, and the one it inherits is no longer read.

final class Session {

    public String user() {
        return "";
    }

    public Session withUser(String user) {
        return this;
    }
}

interface UserOptics {

    @Wither(value = "withUser", getter = "user")
    Lens<Session, String> user();
}

@ImportOptics
interface SessionOpticsSpec extends OpticsSpec<Session>, UserOptics {}

"@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 SessionOpticsSpec<S extends Session> 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<Session>. 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>, U> value(). 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>>. See Spec Interfaces.

record Box<T>(T value) {

    Box<T> withValue(T value) {
        return new Box<>(value);
    }
}

@ImportOptics
interface BoxOpticsSpec extends OpticsSpec<Box> {

    @Wither("withValue")
    Lens<Box, String> value();
}

"@ImportOptics: type '...' names the type parameter 'T' of '...', which hides the 'T' of its enclosing class '...'"

An inner class imported by class literal declares a type parameter under a name its enclosing class already uses.

Fix. Import it through a spec interface, which names the type under type parameters of its own, interface InOpticsSpec<A, B> extends OpticsSpec<Outer<A>.In<B>>, and give each field a @Wither lens. See Generic Spec Interfaces.

class Outer<T> {

    final class In<T> {

        private final T item;

        In(T item) {
            this.item = item;
        }

        public T item() {
            return item;
        }

        public In<T> withItem(T item) {
            return new In<>(item);
        }
    }
}

@ImportOptics({Outer.In.class})
class OuterImports {}

"@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.

A lens declared raw, Lens items(), reads as which the spec declares raw. It is refused for the same reason: the traversal composes onto what the lens focuses, and a raw lens says nothing about that. Declare it with both type arguments, as Lens<Sack, List<String>>.

A lens declared static or private reads as which the spec declares static or private. A method with a body stays on the spec, and the traversal composes through the generated class's lens, so declare items as an abstract Lens method with its copy strategy.

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, Bank {}

record Card(String pan) implements Payment {}

record Bank(String iban) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

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

"@InstanceOf: '...' tests 'Grid', which no '...' can be"

The class @InstanceOf names is a subtype of the source's class, but its own declaration writes a different type where the source type writes one, so no value of the source would pass the test.

Fix. Name a class in @InstanceOf that the source type can be, or declare the prism on a spec of its own over the type the class declares, which the message names: Node<Y[]> for a Grid<Y>. NodeOpticsSpec keeps the source its other methods were written for:

class Node<T> {}

class Grid<Y> extends Node<Y[]> {}

class Counts extends Node<int[]> {}

@ImportOptics
interface NodeOpticsSpec extends OpticsSpec<Node<int[]>> {

    @InstanceOf(Counts.class)
    Prism<Node<int[]>, Counts> counts();
}

@ImportOptics
interface GridOpticsSpec<Y> extends OpticsSpec<Node<Y[]>> {

    @InstanceOf(Grid.class)
    Prism<Node<Y[]>, Grid<Y>> grid();
}

class Node<T> {}

class Grid<Y> extends Node<Y[]> {}

@ImportOptics
interface NodeOpticsSpec extends OpticsSpec<Node<int[]>> {

    @InstanceOf(Grid.class)
    Prism<Node<int[]>, Node<int[]>> grid();
}

"@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.

Where what the test earns is no source type, no focus would build the source back: a Box<?> is no Node<U> for Box<X> extends Node<List<X>>. The message then offers another class, or the prism on a spec of its own over Node<List<X>>, as for a test that would never match.

class Shape {}

class Circle<X> extends Shape {}

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

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

"@InstanceOf: '...' tests 'Outer.Inner', where Y extends X and '...' pins nothing to Outer's X"

A parameter the test pins is bounded by a parameter the source pins nothing to. A bound that only names it, such as Y extends List<X>, reads as List<?>, and the argument the source pins has to be within it, as an argument outside its bound explains.

Fix. Narrow through a predicate and getter of the source type with @MatchWhen, or write the prism by hand with Prism.of. Where you can change the classes, a source that pins X as well lets the test name it.

class Node<U> {}

class Outer<X> {

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

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

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

"@InstanceOf: '...' tests '...', where Y extends Number and U is not a 'Number'"

The source pins a parameter of the class @InstanceOf names to an argument outside that parameter's bound.

Fix. The message ends in one of two lines:

• It declares a spec parameter where one bound will do. The declaration, as in interface NodeOpticsSpec<U extends Number>, keeps every bound the parameter has, so it can replace the one there.
• Otherwise it offers another class for @InstanceOf. The message still lists every bound the argument has to meet, so a spec that can take them all may declare them itself, as in U extends Number & Comparable<U>.

Either way, @MatchWhen narrows through a predicate and getter of the source type instead.

class Node<U> {}

class Gauge<Y extends Number> extends Node<Y> {}

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

    @InstanceOf(Gauge.class)
    Prism<Node<U>, Node<U>> gauge();
}

"@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. Where the narrowed type is no source type, no supertype of it would do. The message then offers another class, the focus's own where that is a source type, or a spec of its own over the type the narrowed class declares.

sealed interface Payment permits Card, Bank {}

record Card(String pan) implements Payment {}

record Bank(String iban) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

    @InstanceOf(Card.class)
    Prism<Payment, Bank> 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 or @ViaBuilder, which rebuild through methods and name no constructor, so a wildcard source type is no obstacle there. For an abstract class or an interface, name a concrete class as the spec's source type, or switch to @Wither or @ViaBuilder likewise. Every other refusal's remedy offers only those two strategies for such a source type.

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();
}

"@ViaCopyAndSet: The generated lens returns the copy it calls '...' on, and drops what '...' returns" (a warning)

The setter is spelt as a wither, withTitle, and may return the source type, but not every method of that name the new value can be passed to returns it. One returns a supertype, a raw type, void, or a type that holds the source type, such as an Optional. So the lens calls it for its effect and hands back the copy. A wither leaves the copy as it was, and then set changes nothing.

Fix. Name a setter that sets the copy, or rebuild the source type with @ViaBuilder or @ViaConstructor. Where @Wither would rebuild through the method the focus binds, the warning offers it in place of naming another setter. Where the method does set the copy it is called on, as a fluent withTitle returning its base type does, annotate the lens method @SuppressWarnings("dropped-result"), or the spec interface to cover each lens it declares.

For this declaration, the warning reads The lens can hand back the result only where every method of that name the new value can be passed to returns a 'Hedge', and 'withTitle(String)' returns 'Shrub'.

class Shrub {

    protected String title = "";

    public Shrub withTitle(String title) {
        Shrub copy = new Shrub();
        copy.title = title;
        return copy;
    }
}

final class Hedge extends Shrub {

    Hedge() {}

    Hedge(Hedge other) {
        this.title = other.title;
    }

    public String getTitle() {
        return title;
    }
}

@ImportOptics
interface HedgeOpticsSpec extends OpticsSpec<Hedge> {

    @ViaCopyAndSet(setter = "withTitle")
    Lens<Hedge, String> getTitle();
}

"@Wither: '...' returns '...', not the source type '...'"

The method a spec's @Wither call binds hands back something other than the source type the spec declares: that type raw, the type under other arguments, or a supertype.

Fix. Name a wither that returns the source type. Where the wither returns the type under fixed arguments, Memo<String> withId(String) on a Memo<T>, declare the spec over that instantiation, OpticsSpec<Memo<String>>, and it serves as it is. Otherwise rebuild the source type with @ViaBuilder or @ViaConstructor, or with @ViaCopyAndSet through a setter that sets the copy it is called on. The same wither named as that setter has its new value dropped, and draws the dropped-result warning. See Copy Strategies.

final class Memo<T> {

    private final String id;

    Memo(String id) {
        this.id = id;
    }

    public String id() {
        return id;
    }

    @SuppressWarnings("rawtypes")
    public Memo withId(String id) {
        return new Memo<>(id);
    }
}

@ImportOptics
interface MemoOpticsSpec<T> extends OpticsSpec<Memo<T>> {

    @Wither(value = "withId", getter = "id")
    Lens<Memo<T>, String> id();
}

"@Wither: '...' has no method '...' for the generated lens to call"

The method a spec's @Wither names is not one the generated class can call on the source type: the name is misspelt, or the method is private, or package-private in another package. Where the name is declared but out of reach, the message says so rather than claiming the type has no such method.

Fix. Correct the name. The message lists the source type's withers, its one-parameter instance methods that hand it back, with the value each one takes. It offers the with method you likely meant: one a near miss away, or one naming the same value, withId for id or setId. Where the type has none, rebuild it with @ViaBuilder, @ViaConstructor or @ViaCopyAndSet. See Copy Strategies.

final class Licence {

    private final String id;

    Licence(String id) {
        this.id = id;
    }

    public String id() {
        return id;
    }

    public Licence withId(String id) {
        return new Licence(id);
    }
}

@ImportOptics
interface LicenceOpticsSpec extends OpticsSpec<Licence> {

    @Wither(value = "withIdentifier", getter = "id")
    Lens<Licence, String> id();
}

"@Wither: No method '...' of '...' takes the lens's focus type '...'"

The source type has methods of the name @Wither gives, and none of them takes the value the lens sets, whose type is the lens's focus. Where none takes one argument, the name is usually an accessor's, id written for withId, and the message offers the wither for that value. The @ViaBuilder and @ViaCopyAndSet messages offer the setter for that value the same way, in the strategy's convention.

Fix. Name a wither that takes the value the getter reads, or point getter at an accessor one of the listed methods takes and declare the focus as its type. The focus alone rarely settles it: the getter pins it from below, so a focus wide enough to read the getter is usually too wide for a parameter the getter's own type already failed. The exception is a focus wider than the wrapper of a primitive getter, Number over an int one, which is never unboxed: there the message offers the wrapper, Integer, as the focus to declare. Otherwise rebuild the source type with @ViaBuilder, @ViaConstructor or @ViaCopyAndSet. Where the parameter is a type the source type's wildcard stands for, the T of withValue(T) on a spec over Cell<?>, declare the spec over the type the wildcard stands for, a type parameter of the spec if need be: interface CellOpticsSpec<T> extends OpticsSpec<Cell<T>>.

final class Tally {

    private final String count;

    Tally(String count) {
        this.count = count;
    }

    public String count() {
        return count;
    }

    public Tally withCount(Integer count) {
        return new Tally(String.valueOf(count));
    }
}

@ImportOptics
interface TallyOpticsSpec extends OpticsSpec<Tally> {

    @Wither(value = "withCount", getter = "count")
    Lens<Tally, String> count();
}

"@Wither: The generated call to '...' cannot choose between '...' and '...'"

More than one overload of the wither takes the lens's focus, and none takes it more closely than the rest, so javac would report the generated call as ambiguous.

Fix. Declare the lens's focus as the parameter type of the overload you mean. Below, a Lens<Ident, CharSequence> reaches only withId(CharSequence), and the getter's String is still a CharSequence.

final class Ident {

    private final String id;

    Ident(String id) {
        this.id = id;
    }

    public String id() {
        return id;
    }

    public Ident withId(java.io.Serializable id) {
        return new Ident(id.toString());
    }

    public Ident withId(CharSequence id) {
        return new Ident(id.toString());
    }
}

@ImportOptics
interface IdentOpticsSpec extends OpticsSpec<Ident> {

    @Wither(value = "withId", getter = "id")
    Lens<Ident, String> id();
}

"@Wither: '...' is static, so the generated lens cannot rebuild a '...' through it"

The overload of the wither that the lens's focus binds is a static method.

Fix. Declare the lens's focus as the parameter type of an instance overload, which is what binds it instead; or name an instance wither; or rebuild the source type with @ViaBuilder, @ViaConstructor or @ViaCopyAndSet.

final class Token {

    private final String id;

    Token(String id) {
        this.id = id;
    }

    public String id() {
        return id;
    }

    public static Token withId(CharSequence id) {
        return new Token(id.toString());
    }

    public Token withId(Object id) {
        return new Token(String.valueOf(id));
    }
}

@ImportOptics
interface TokenOpticsSpec extends OpticsSpec<Token> {

    @Wither(value = "withId", getter = "id")
    Lens<Token, String> id();
}

"'...' has no method '...()' for the generated lens to read the value it focuses"

Every copy strategy reads with the same lambda, source -> source.getX(). @Wither and @ViaBuilder name that accessor in their getter; @ViaCopyAndSet and @ViaConstructor read through the lens method's own name. The name here is not a zero-parameter instance method the generated class can call: it is misspelt, static, takes an argument, or is out of reach.

The same shape of message covers every name a strategy calls with no argument, each ending on what the generated lens wanted it for:

Fix. Point the strategy's attribute at a method the type declares. The message offers one where the name is a near miss, or the same accessor under another naming convention, however many letters apart: getName for name, name for getName, isActive for getActive. On a protobuf-java message it offers the getter that reads a repeated or map field whole, getTagsList for tags or getTags, and getPointsMap for points. No offer is ever a deprecated method, such as a map field's getPoints(), since the generated file's call to one fails a build under -Werror. Where the strategy has no such attribute, name the lens method after the accessor it reads.

final class Permit {

    private final String id;

    Permit(String id) {
        this.id = id;
    }

    public String getId() {
        return id;
    }

    public Permit withId(String id) {
        return new Permit(id);
    }
}

@ImportOptics
interface PermitOpticsSpec extends OpticsSpec<Permit> {

    @Wither(value = "withId", getter = "getIdentifier")
    Lens<Permit, String> id();
}

"'...()' reads '...', not the lens's focus '...'"

The accessor exists, and reads a value of another type. LocalDate is the standard example: withMonth takes an int, while getMonth() reads a Month, so the two do not make a lens between them.

Fix. Point the strategy's getter at an accessor that reads the focus, getMonthValue() for that pair, or declare the lens over what this one reads and rebuild through a method that takes it. Where the strategy reads through the lens method's own name, rename the lens method.

enum Month { JANUARY, FEBRUARY }

final class Renewal {

    private final int month;

    Renewal(int month) {
        this.month = month;
    }

    public Month getMonth() {
        return Month.values()[month - 1];
    }

    public int getMonthValue() {
        return month;
    }

    public Renewal withMonth(int month) {
        return new Renewal(month);
    }
}

@ImportOptics
interface RenewalOpticsSpec extends OpticsSpec<Renewal> {

    @Wither(value = "withMonth", getter = "getMonth")
    Lens<Renewal, Integer> month();
}

Unchecked reads and rebuilds through a raw type

The external class declares an accessor, a builder or a supertype raw, or the spec writes the focus raw. The generated lens would read or rebuild through it in a way javac flags as unchecked. These messages report it, under the strategy's own tag:

Fix. Read and rebuild through members that name their types with arguments: an accessor that reads List<String>, a method that takes it, a builder whose steps hand back Builder<T>. Where the class offers only raw members, declare the lens over the raw type they read, Lens<Shelf, List>, with @SuppressWarnings("rawtypes") on the lens method. Where a wildcard of the source stands in the parameter, declare the spec with a type argument in its place and the focus as the type the method then takes: interface BinOpticsSpec<T> extends OpticsSpec<Bin<T>> with Lens<Bin<T>, List<T>>. Where toBuilder() hands the wildcard back, point toBuilder at a method that hands back the builder with its type arguments. Otherwise rebuild with another strategy.

final class Shelf {

    private final List items;

    Shelf(List items) {
        this.items = items;
    }

    public List getItems() {
        return items;
    }

    public Shelf withItems(List items) {
        return new Shelf(items);
    }
}

@ImportOptics
interface ShelfOpticsSpec extends OpticsSpec<Shelf> {

    @Wither(value = "withItems", getter = "getItems")
    Lens<Shelf, List<String>> items();
}

"'...' has no method '...' for the generated lens to set through"

The setter a @ViaBuilder or @ViaCopyAndSet names is not a method of the type it is called on: the builder for the first, the source type for the second.

Where the name exists, the call is held to what a wither's is, under the strategy's own tag: takes the lens's focus type where no overload takes the focus, cannot choose between where more than one does, and is static, so the generated lens cannot set through it where the one it binds is static, since a static method never reads the value it is called on. Where the focus is a wildcard and no method of the name takes one argument, the message says takes one argument instead. On a spec over Bag<?>, a toBuilder() declared to hand back a Builder<List<T>> hands back a builder of lists of the one type the wildcard stands for. No focus the spec can write is such a list. The message then says A parameter that a wildcard of 'Bag<?>' stands in takes no value at all, and lists the builder's methods as toBuilder() declares them. The fix is the wither's: declare the spec over the type the wildcard stands for. Where the wildcard is the builder's own, as in a toBuilder() that hands back a Builder<?>, point toBuilder at a method that hands back the builder with its type arguments.

Fix. Set the strategy's setter to a method that type declares, and one that takes the value the getter reads. The message offers one where the name is a near miss, or names the same value in the strategy's convention. Under @ViaBuilder, it offers a fluent builder's name, a protobuf builder's setName or a withName step, as the builder declares them. For a protobuf repeated or map field it offers the addAllName or putAllName that sets the field whole. Since the setter defaults to the lens method's name, a lens named getName is offered name. Under @ViaCopyAndSet, it offers only a set method, near miss or not. A bare or with method may hand back a copy, and @Wither is the strategy for one of those.

final class Server {

    private String host;

    Server() {}

    Server(Server other) {
        this.host = other.host;
    }

    public String host() {
        return host;
    }

    public void setHost(String host) {
        this.host = host;
    }
}

@ImportOptics
interface ServerOpticsSpec extends OpticsSpec<Server> {

    @ViaCopyAndSet(setter = "setHostname")
    Lens<Server, String> host();
}

@ViaBuilder: the chain the lens rebuilds through

@ViaBuilder rebuilds with source.toBuilder().setter(newValue).build(), and each step is called on what the step before it hands back. Two messages report a chain that does not lead back to the source type: 'toBuilder()' hands back 'int', which is not a builder to set through, and 'build()' returns 'String', not the source type 'Waybill'. A setter that returns void reads hands back 'void', which is not a builder to build from. A subclass whose toBuilder() comes from its parent reads 'Dog' inherits 'toBuilder()' from 'Animal', whether the parent's builder lacks the setter or builds an Animal.

Fix. Name the methods the type's own builder declares. A Lombok @SuperBuilder subclass needs toBuilder = true of its own, since the toBuilder() it inherits builds its parent. Where the type has no such chain, rebuild it with @Wither, @ViaConstructor or @ViaCopyAndSet.

final class Waybill {

    private final String id;

    Waybill(String id) {
        this.id = id;
    }

    public String id() {
        return id;
    }

    public Builder toBuilder() {
        return new Builder();
    }

    static final class Builder {

        private String id;

        public Builder id(String id) {
            this.id = id;
            return this;
        }

        public String build() {
            return id;
        }
    }
}

@ImportOptics
interface WaybillOpticsSpec extends OpticsSpec<Waybill> {

    @ViaBuilder
    Lens<Waybill, String> id();
}

@ViaConstructor: the order the lens rebuilds through

@ViaConstructor rebuilds with new S(source.a(), newValue, source.c()): the accessor each name in the order reads, and the new value where the lens method's own name stands. The order is parameterOrder, or the one the constructor's parameter names give when you leave it out. These messages report an order the generated call cannot rebuild through:

Fix. Where the constructor's parameter names give an order the call would rebuild through, the message ends on it, ready to paste: @ViaConstructor(parameterOrder = {"x", "y"}). Where the lens's focus is what no constructor takes, it names the type the getter reads, to declare as the focus instead. Where the names give no order, or the order read from them would rebuild through the wrong constructor, write the order of the one the lens should rebuild through. Where no constructor takes the lens's value, or javac cannot choose one, rebuild the source type with @Wither, @ViaBuilder or @ViaCopyAndSet. A lens named after an alias, price() for a parameter cents, can take the accessor's own name instead. A parameter can be named after an accessor that reads something else, as Money(long amount, ...) beside an amount() that reads pounds rather than pence. The processor still holds the order to that name, and the lens needs another strategy.

final class Point {

    private final int x;
    private final int y;

    Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public int x() {
        return x;
    }

    public int y() {
        return y;
    }
}

@ImportOptics
interface PointOpticsSpec extends OpticsSpec<Point> {

    @ViaConstructor(parameterOrder = {"y", "x"})
    Lens<Point, Integer> x();
}

final class Label {

    private final String id;
    private final String tag;

    Label(String id, String tag) {
        this.id = id;
        this.tag = tag;
    }

    public String id() {
        return id;
    }

    public String tag() {
        return tag;
    }
}

@ImportOptics
interface LabelOpticsSpec extends OpticsSpec<Label> {

    @ViaConstructor(parameterOrder = {"id"})
    Lens<Label, String> id();
}

final class Duo {

    private final Integer a;
    private final Integer b;

    Duo(int a, Integer b) {
        this.a = a;
        this.b = b;
    }

    Duo(Integer a, int b) {
        this.a = a;
        this.b = b;
    }

    public Integer a() {
        return a;
    }

    public Integer b() {
        return b;
    }
}

@ImportOptics
interface DuoOpticsSpec extends OpticsSpec<Duo> {

    @ViaConstructor(parameterOrder = {"a", "b"})
    Lens<Duo, Integer> a();
}

final class Sticker {

    private final String label;
    private final String note;
    private final String[] parts;

    Sticker(String label, String note, String... parts) {
        this.label = label;
        this.note = note;
        this.parts = parts.clone();
    }

    public String label() {
        return label;
    }

    public String note() {
        return note;
    }

    public String[] parts() {
        return parts.clone();
    }
}

@ImportOptics
interface StickerOpticsSpec extends OpticsSpec<Sticker> {

    @ViaConstructor(parameterOrder = {"note", "label"})
    Lens<Sticker, String> label();
}

final class Sum {

    private final int x;
    private final int y;

    Sum(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public int x() {
        return x;
    }

    public int y() {
        return y;
    }

    public int total() {
        return x + y;
    }
}

@ImportOptics
interface SumOpticsSpec extends OpticsSpec<Sum> {

    @ViaConstructor
    Lens<Sum, Integer> total();
}

"@ViaConstructor: 'parameterOrder' ... passes nothing for '...', which '...' takes" (a warning)

A written order rebuilds through the constructor its call binds, even one that takes fewer values than the source holds. Beside Fee(long amount, String currency), {"amount"} binds Fee(long amount), and every set then hands back a Fee in that constructor's default currency. The warning names every value a longer constructor takes that the order passes nothing for, from each longer constructor; for a record, every component.

Fix. Pass it: where a constructor's names give an order that passes it, the warning offers that order, ready to paste, @ViaConstructor(parameterOrder = {"amount", "currency"}). A shorter constructor can work the value out on purpose: a Rect(int w, int h) works out the area a Rect(int w, int h, int area) record holds. Then annotate the lens method @SuppressWarnings("shorter-constructor"), or the spec interface to cover each lens it declares. Where no one constructor takes all the values, as Knot(int x, int y) and Knot(int x, long z) take one each, no order passes them all, and the warning says so rather than offer one.

For this declaration, the warning reads 'parameterOrder' {"amount"} passes nothing for 'currency()', which 'Fee(long amount, String currency)' takes.

final class Fee {

    private final long amount;
    private final String currency;

    Fee(long amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }

    Fee(long amount) {
        this(amount, "GBP");
    }

    public long amount() {
        return amount;
    }

    public String currency() {
        return currency;
    }
}

@ImportOptics
interface FeeOpticsSpec extends OpticsSpec<Fee> {

    @ViaConstructor(parameterOrder = {"amount"})
    Lens<Fee, Long> amount();
}

"@ImportOptics: '...' pairs more than one wither with the field '...'" (a note)

A class imported by class literal spells one field's accessor more than one way, and has a wither for each: int n() with withN(int), and String getN() with withN(String). Both pair with the field n, and a class can carry only one lens of that name.

Fix. Nothing, where the lens you wanted is the one generated: the note says which. Where you wanted the other, import the type through a spec interface and name the pair yourself with @Wither(value = "withN", getter = "getN"), importing it there rather than by class literal, or the note stays on every build.

public final class Counter {

    private final int n;

    public Counter(int n) {
        this.n = n;
    }

    public int n() {
        return n;
    }

    public String getN() {
        return String.valueOf(n);
    }

    public Counter withN(int n) {
        return new Counter(n);
    }

    public Counter withN(String n) {
        return new Counter(Integer.parseInt(n));
    }
}

@ImportOptics({Counter.class})
class CounterImports {}

"@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. Where what an @InstanceOf test earns is no source type, no focus could take it and still be one. The message then offers another class, or a spec of its own over the type the class declares.

sealed interface Payment permits Card, Bank {}

record Card(String pan) implements Payment {}

record Bank(String iban) implements Payment {}

@ImportOptics
interface PaymentOpticsSpec extends OpticsSpec<Payment> {

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

"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, Bank {

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

    default Card asCard() {
        return (Card) this;
    }
}

record Card(String pan) implements Payment {}

record Bank(String iban) 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, Bank {}

record Card(String pan) implements Payment {}

record Bank(String iban) 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. A raw bound on the interface's own type parameter is not refused: the bridge repeats it in its class declaration and carries @SuppressWarnings("rawtypes") there.

@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 public the class the message names, which may be one enclosing the type. Where the type sits beside the interface, removing targetPackage also works, since the bridge is then written there, and the message offers it where it does.

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 takes its witness type from the Traverse argument, but its element type only from where the result goes. In a chain such as .traverseOver(...).getAll(user), the element type falls back to Object, and javac reports incompatible types: List<Object> cannot be converted to List<Role>.

Fix. Widen through each(EachInstances.fromTraverse(...)), which takes the element type from the Kind the path focuses on, so it holds in a chain too:

TraversalPath<Operator, Role> allRoles =
    rolesPath.each(EachInstances.fromTraverse(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<OrgChart, OrgUnit>   units    = OrgChartFocus.units();
TraversalPath<OrgChart, OrgMember> members  = units.via(OrgUnitFocus.members());
TraversalPath<OrgChart, Integer>   salaries = members.via(OrgMemberFocus.salary());

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

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

Fix. Use the typed form at each hop. It takes the element type from the List the path focuses on, so no hop needs it spelled out:

TraversalPath<OrgChart, Integer> allSalaries =
    FocusPath.of(OrgChartLenses.units())
        .each(EachInstances.listEach())
        .via(OrgUnitLenses.members())
        .each(EachInstances.listEach())
        .via(OrgMemberLenses.salary());

"No suitable method found for each(...)" on a typed step

The path does not focus on the container the step names: EachInstances.listEach() takes a path that focuses on a List, and FocusPaths.optionalSome() one that focuses on an Optional.

Fix. Give the step the instance for what the path does focus on. A generated collection path already focuses on each element, so it needs no step of its own, and a Set, a Map or another container takes its own Each. A path over a List<? extends T> takes an Iso to List<T> first, and one over a Kind<F, ? extends T> an Iso to Kind<F, T>, as 0.6.0 deprecation migration shows.

// Rejected: the generated path already focuses on each OrgUnit, not on a List
TraversalPath<OrgChart, OrgUnit> units = OrgChartFocus.units().each(EachInstances.listEach());

"each() in org.higherkindedj.optics.focus.FocusPath has been deprecated and marked for removal" (a warning)

A Focus path's no-argument each(), some(), head(), last(), tail(), init(), cons(), snoc(), headTail() or initLast() is deprecated for removal in 0.6.0, and so are its at(index), atKey(key) and traverseOver(traverse). The warning names the method and the path type, a navigator included.

Fix. Write its typed form: the same verb, given an instance that names the container, such as each(EachInstances.listEach()) or some(FocusPaths.optionalSome()). Removals in 0.6.0 gives each one. The MigrateDeprecationsTo0_6_0 recipe rewrites the calls it can and marks the rest, as 0.6.0 deprecation migration says.

// Warned: each() takes its element type from the assignment, not from the path
TraversalPath<OrgChart, OrgUnit> units = FocusPath.of(OrgChartLenses.units()).each();

"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<ShelfLabel, Barcode> lens = Lens.of(ShelfLabel::barcode, (label, code) -> new ShelfLabel(code));

"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:

Saver 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: Focus DSL Reference