You are reading GraphMaquina 2.0.3. The latest version is 2.0.6.

Diagnostics and troubleshooting

Read the full compiler message, including the source location and member it identifies. A wrong enum type or symbol category may be an ordinary javac error rather than an SG diagnostic: writing a state where an identifier belongs, or a constant of another machine's catalogue, is refused by javac before any GraphMaquina code runs. A mistyped generated symbol, such as DocActionsRefs.Publsh.class, is javac's alone to refuse too, as cannot find symbol once annotation processing is over: the processor still reports every other problem of that machine's declarations, but none about its graph as a whole, and generates no companion for it. A class another annotation processor generates can still be named, such as an exception in failsOn, and so can a constant it declares, such as the text of a policy, the reason of a rejection or the seconds of a timeout: the processor builds that machine, and a set that holds it, in the round that brings the class, and a constant no round resolves is javac's alone to refuse, like a mistyped symbol. javac refuses such a constant before any processor runs, as expression not allowed as annotation value, in an annotation repeated without its container: list those annotations in their container instead, such as @DocsGraph.StatePolicies({...}). The values of annotations GraphMaquina does not own are left to javac, so an annotation of your own on a facade may even name the machine's companion.

The exceptions the library throws at runtime are on their own page, Runtime exceptions.

Contents

Graph and declaration diagnostics

Code Meaning / corrective action
SG102 Duplicate (from, id) key, or a state that declares two policies or rejects one identifier twice. Two edges that merely share endpoints are not a duplicate.
SG103 Blank reason on a policy or a rejection. A missing one does not compile with annotations, whose reason elements have no default, and is a NullPointerException in the DSL.
SG105 Duplicate guard: list each guard once per transition, and give the guards of one transition distinct names, which a rejection reports. A generated guard takes its member's simple name, so one transition cannot ask for two hosts' guards whose members share a name; a DSL guard takes the name given or, without one, its class's simple name.
SG106 DSL callback has no inferable name: provide the explicit name overload for a lambda.
SG107 Blank DSL callback or condition name: supply a nonblank label.
SG108 Invalid automatic order. A state with two or more automatic edges must declare exactly one automaticOrder, which names each of those edges once and nothing else. Refused: no order; an order that names an identifier that is not an automatic edge of that state, or leaves one out, or names one twice; an order on a state with fewer than two automatic edges; and more than one order on a state. A state with more than one order reports only that. This code and SG109, SG206, SG305 and SG807 are reported only once the graph has no other problem.
SG109 An edge without guards comes before another edge in an automatic order. An edge without guards is always chosen, so the edges after it could never be: put it last.
SG201 Missing or repeated DSL initial declaration.
SG202 A terminal declares an outgoing edge, including a self-loop, or a non-terminal declares none.
SG203 Unreachable state: add a real path from initial or remove the state.
SG204 Unauthorised cycle: list an intentional cycle's state in allowsCycle. One witness is reported per cyclic strongly connected component, deterministically, rather than one message per elementary cycle. allowsCycle does not authorise a cycle of automatic edges: once the graph has no other problem, such a cycle is SG206, so fixing an SG204 can reveal an SG206.
SG205 Unused cycle allowance: the named state belongs to no cycle.
SG206 The automatic edges form a cycle, directly or through a continuing failure route (onFailureAndContinue or recoverAndContinue), which jumps from the origin of the edge that failed to the destination of its recovery edge. allowsCycle does not authorise it, and an automatic self-loop is one. A cycle that also holds a manual edge is not this code: SG204 covers it. One witness is reported per cyclic component.
SG301 Invalid failure route: onFailure or a recovery rule names this edge's own key, or no edge with that identifier leaves the same origin. Each origin of an identifier is checked on its own.
SG302 Forbidden throwable type in failsOn or in a recovery rule: Throwable, Exception, RuntimeException, an Error, a library exception, a CancellationException or one of its subtypes, or exactly CompletionException or ExecutionException, which the runtime unwraps before matching whenever they carry a cause. In the DSL, also a class that is not a Throwable, which only a raw type lets through. Use a specific foreign throwable type, usually an exception, or the type of the wrapped cause.
SG303 A recovery rule names a class that is not a failure kind. A failure kind is a named final class or record that implements FailureKind and is not an interface, an enum, a local or anonymous class, or a Throwable: declare one as public record Unavailable() implements FailureKind { }.
SG304 Ambiguous recovery rules: two rules of one edge name the same failure kind, or one throwable type is declared twice in a rule, in two rules, or in a rule and in the edge's failsOn. A type that only failsOn repeats is accepted.
SG305 A continuing failure route leads to a state with no automatic edge, so continuing has no effect: remove the continuation, or declare an automatic edge from that state. With annotations, also onFailureContinues on an edge that declares no onFailure: there is no route to continue, so declare the onFailure or drop the flag.
SG401 A watch rule names an identifier with no edge from the watched state.
SG402 A terminal state declares a watch.
SG403 More than one watch on the same state.
SG404 A watch has no rules. In the DSL, also a when(...) that no execute(...) follows, and an execute(...) with no pending when(...).
SG405 A watch declares neither or both of owner and ownerLookup; it declares exactly one.
SG502 Invalid machine or set declaration, such as a machine interface that does not carry its generated Definition, an unsupported nested or local interface, a machine declared as a class that implements Machine instead of as an interface, or a set that is not an interface extending Machines. A machine, interface or class, that does not extend Machine is SG601, unless it is local.
SG503 Missing, incompatible or ambiguous public property accessor, ambiguous writer overloads included.
SG504 Invalid operation annotation or signature. An operation is Outcome<E, S, T> operation(E) or operation(E, I) and carries at least one Transition of its own vocabulary; an abstract method of the facade that carries neither a Transition nor a Check of it is refused. Zero, three or more parameters and a wrong entity or return type are rejected; operations with input also reject varargs and method type parameters. Also refused: a Transition or a Check on a default, static or private method of the facade; an abstract method the facade inherits from another interface, which its companion would not implement; a method that redeclares a Machine method or a public method of Object with vocabulary of its own, or with a result the companion cannot return; and an instance method of the facade, declared or inherited, abstract or default, with the signature of the companion's static graph(...), which takes the definition of each machine it binds as a sub-machine, then one parameter per class with instance members the machine binds, or none. That last refusal is reported once the machine's declarations have no other error and none of its vocabulary is misplaced, since fixing one can change what graph(...) takes; an error of its graph as a whole, such as SG202, SG203 or SG701, and a refused companion name (SG603, or SG602 when a previous compilation left its companion) are reported beside it.
SG505 Exported method does not uniquely fit the action, guard, hook, condition or lookup role, including the default afterCommit binding on Definition. Also an instance member of a generic host, or of an inner class of a generic class, which generated code could only call raw (export it from a non-generic subclass marked @GraphBindings, or make it static), and a binding whose host or parameter types the companion's package cannot access.
SG507 Invalid transition elements: empty from, onFailure, failsOn or recovery rules without an action, or a timeout without an asynchronous action. In the DSL, also an edge never closed with endTransition(), and an edge that declares more than one action, onFailure or timeout.
SG508 Watch rule must choose exactly one supported predicate alternative.
SG509 Invalid peer-machine type, a peer whose entity is a parameterized type, a watched peer whose types the watcher's package cannot access, or a sub-machine whose entity, states or transitions its parent's package cannot access.
SG510 Invalid set accessor, duplicate/missing machine or missing watched peer in the set. Also an accessor the set inherits from another interface, two machines that write the same entity and state enum, a machine whose types the set's package cannot access, and an instance method of the set, declared or inherited, abstract or default, with the signature of the companion's static builder(...), which takes the timeout shared by the set's asynchronous machines, when it has any, then every class with instance members its machines use. That last refusal is reported only once the set's accessors and machines have no other error, since fixing one can change what builder(...) takes.
SG511 Invalid timeout duration. In @Timeout, neither seconds nor nanos may be negative, nanos is at most 999 999 999 and the two may not both be zero; in the DSL, the Duration must be positive.
SG512 A Check names an identifier no operation of its facade executes: one that only edges declared on the facade itself use, such as a failure route or a cascade-only or watch-only edge, the exit of a sub-machine, or one without an edge. Name the identifier of one of the facade's operations. When a method of the facade declares a Transition of that identifier but is refused, as SG504, SG703 or an error of one of its edges, only that refusal is reported.
SG513 A check does not repeat the parameters of the operation it checks. It is declared as Eligibility<E, S, T> check(E), or as check(E, I) when that operation takes an input of type I, with the same entity and input types, without varargs or method type parameters.
SG514 Two checks name the same operation, or one method carries both a Transition and a Check. An operation has one check at most, declared on a method of its own.
SG515 An automatic edge, written on an operation or as a branch of its identifier on the interface, runs an operation that takes an input. An automatic attempt carries no input to hand it: drop automatic, or give the operation no input.
SG701 A non-terminal state declares no rejection policy. A terminal state without one refuses every request with terminal state <NAME> accepts no transitions.
SG702 One (from, transition) key both declares an edge and rejects the identifier.
SG703 Two annotations of one method name different identifiers, or two methods claim the same identifier. A type-level Transition may add branches of an identifier a method owns while their keys stay disjoint.
SG801 A sub-machine's exits do not match the terminal states of its child: a terminal state of the child has no exit or more than one, or an exit is declared on a state that is not terminal in the child. Two terminal states may map to the same identifier.
SG802 A sub-machine's exit names an identifier with no edge from the state the sub-machine is bound to.
SG803 A terminal state holds a sub-machine, or one state holds more than one.
SG804 An identifier that a sub-machine's exit names is also named, from the state the sub-machine is bound to, by an edge's onFailure or recovery rule, or by a rule of that state's watch. The same identifier from another state is not an exit. With annotations, an operation of the facade may not execute an exit either: it requests its identifier from whichever state the machine is in, the bound state included.
SG805 A machine's sub-machines contain the machine again, directly or through their own sub-machines. The DSL compares machine keys along the chain of child definitions, so it takes a second definition of the machine's own key, and prints one shortest path. The processor follows the sub-machines each child declares in turn, and reports one shortest path at the binding it starts with, on every machine of the cycle.
SG806 A sub-machine declared with annotations does not declare the ways between its entities that it needs: a child over another entity than the parent's needs child and exactly one of parent or parentLookup, and a child over the parent's own entity takes none of the three. Also a set that holds a machine but not the machine bound to one of its states, which the set could not build, whether the parent was generated by this compilation or comes from a dependency jar.
SG807 An automatic edge leaves a state that holds a sub-machine, whether or not the edge is one of the sub-machine's exits. An exit is reserved for the terminal state of the child, and any other automatic edge would detach the child before its own chain runs.

Generation and typed binding diagnostics

Code Meaning / corrective action
SG599 The processor could not write a generated source, provisional export index or processor inventory. Inspect the named type/path and underlying error; correct the output path, permissions, available space or reported file collision, then rerun the full generation/compilation lifecycle. See processor output failures.
SG601 Bootstrap declaration cannot be resolved, is ambiguous or contradicts another declaration. Machine<E, S, T> must resolve to a concrete entity type and two distinct enums, one for states and one for transition identifiers. Also a facade, interface or class, that does not extend Machine, such as interface Tickets extends Runnable, unless it is local, which is SG502, a facade that declares type parameters, a parameterized entity type, such as Ticket<String> or an inner class of a parameterized class, such as Store<String>.Doc, a facade or enum the vocabulary's package cannot access, a marker whose annotation type is not on the generator's classpath, and an original source javac cannot parse at the compilation's release.
SG602 A manifest, an inventory or an export index is missing, incompatible, stale or malformed, or written in a schema this version does not read, or the export indexes of two classpath entries describe one machine. Any of these files, or the request, is malformed when it holds a number whose exponent is out of range, such as 1e99999999999, or escapes in a string or a name a surrogate that is not half of a pair, such as \ud800, which no UTF-8 file can hold, and a manifest is also malformed when its processor inventory is no path, such as one holding a NUL character, or when an owned source it lists is not a relative path to a Java source: one that no path can spell, such as one holding a NUL character, one that is absolute or has a root, one with a .. segment, one that names the directory itself, such as ., or one that is no .java file, such as x. A dependency, a jar or a directory of classes, that carries no export index, as an assembly step that drops META-INF/graphmaquina leaves it, or whose index does not list a machine or a generated symbol its classes carry, because it is stale or another build's, as an assembly step that overwrites META-INF/graphmaquina leaves it, is reported naming that jar or directory: by the generator at a machine that declares such a machine a peer with @GraphPeers, before it publishes anything, and otherwise where a set holds such a machine or a declaration binds such a symbol; a peer for which the generator can name no such jar or directory is reported as a machine no export index it reads lists. An index that describes a peer otherwise than the classes beside it is stale too, and the generator reports it at the machine that declares the peer, naming that jar or directory: an enum it names declares other constants, or the same in another order, or the peer does not extend Machine over those two enums: it extends it over other enums, over a type that is no enum or a type variable, raw, through a raw supertype, or not at all. Either way, package the index its StateGraph build publishes with its classes, or rebuild the dependency through the complete lifecycle. A peer that passes Machine a state or transition enum the classpath does not declare, or has a supertype the classpath does not declare and reaches Machine through none it declares, because that type's artifact does not reach it or the producer's artifact lost the type, is reported by the generator at the machine that declares the peer, naming that jar or directory and the type, and a dependency's machine that passes Machine an enum the classpath does not declare is reported by the processor, naming the annotation manifest and the enum, even when nothing uses it: add the dependency that declares the type to the classpath, or rebuild the producer. A machine that the export indexes of two different jars or directories on the classpath both describe, as two versions or two copies of one producer, is refused by the generator before it publishes anything, naming both entries in classpath order: keep one artifact of its producer on the classpath; an entry the classpath lists twice is read once and is no such duplicate. So is a machine of the compilation that the export index of a jar or directory on the classpath describes too, anchored at the machine and naming that entry: keep one declaration of the machine. Run the full generation/compilation lifecycle with aligned versions; a work directory whose manifest or ownership inventory is malformed, or written in a schema this version does not read, needs one clean. Also a machine javac compiled implicitly, from the source path, which the processor never saw, reported where the index or a set names it: pass every source of the compilation to javac. A companion of a previous compilation that nothing retired is reported too: run the lifecycle, or clean. Completion reports a class output without the SourceFile attribute: compile with javac's default debug setting, with -g, or with a -g: list that includes source. The generator also refuses a source encoding that names no charset of the JVM it runs under: name one that JVM supports, such as UTF-8.
SG603 Generated output or export collision, a name generated code cannot write, or an output path the generator may not use. Two names normalize to the same PascalCase spelling; a generated type already exists as an original source, in a file at the same path below its source root as the generated file below the generated one, or in another file, which javac would report as a duplicate class, as a class of the classpath, or as a file of the generated directory the previous generation did not own; an original file or type differs from a generated one, or two generated types or two symbol types of one container differ from one another, only in case where the volume does not tell names apart; an existing type takes a companion's name; a type, member type or constant in the scope of a generated file takes over a name that file writes, such as a type of its package named io, java or like a java.lang type; or one canonical name names two types, because a class of the unnamed package is named like a package: two machines, one of the package and one nested in the class, which a manifest names by that name alone, or two types in a class file of the unnamed package that the generator has to tell apart, such as two of its supertypes, which it cannot do by their canonical name. The diagnostic names both sides; rename one of them and its references. The generator's steps also refuse an inventory entry that is not a file under its output root, such as a blank one, one that no path can spell, as with a NUL character, or one that is absolute, has a root, names the root itself or leads out of it, and a binary that is no .class file or a source that is no .java file; an inventory entry whose file they would remove through a symbolic link inside its output root that leads out of it; and a generated source that would be written through such a link. Remove the link; clean a build whose inventory holds such an entry.
SG604 Invalid or contradictory export/role, or a host its generated references container cannot access, such as a private nested class, or cannot name at all: a marker written in a local or anonymous class, on the class or on one of its members. There, as javac reads it, an annotation named like a marker means a member type of a class around it first, such as one inherited from a supertype, and is then no marker; one inside a class whose supertype the generator cannot resolve is let through. Also a static method exported through a @GraphBindings host that hides it, which the generator could not tell because a parameter is a type variable. Check markers and exported signatures.
SG605 Symbol has no valid original member, or belongs to the wrong host/role. Use the correct generated reference.
SG606 Graph vocabulary or the vocabulary of a pair belongs to another machine or pair, or sits where no machine reads it: on anything but a @GenerateGraphApi interface and its abstract methods. On a default, static or private method of its own facade it is SG504.
SG607 Too many values in an optional singleton element such as action, onFailure, timeout, afterCommit, When.condition, When.allIn, When.anyIn or When.noneIn, which hold one state each, the child, parent or parentLookup of a Submachine, or the owner or ownerLookup of a Watch. recoveries is no such element: it holds any number of rules, and several rules are never several fallbacks.
SG608 Invalid or duplicated peer, a peer that no watch or sub-machine of the machine uses, a watch or a sub-machine of a peer the machine does not declare, a peer that is neither a @GenerateGraphApi machine of this compilation, nor one the export index of a dependency describes, nor a class marked @GenerateGraphApi that a dependency on the classpath carries (that one is SG602), or a peer whose types the owner's package cannot name.

Common build problems

Symptom Remedy
TicketsGraph / TicketRefs cannot be found Run generation before javac; check processor participation and original source roots.
Gradle plugin cannot resolve Declare the repository that holds it in pluginManagement.repositories: mavenCentral(), or the internal repository that serves your GraphMaquina artifacts.
Core resolves but Maven plugin does not Configure <pluginRepositories> as well as <repositories> for an internal repository.
Processor reports no manifest Use the Gradle plugin or add Maven's per-execution manifest arguments and six goals.
A Lombok accessor is missing Put Lombok first on the processor path, or provide a public handwritten accessor.
A newly renamed symbol still appears Run the normal lifecycle, check whether generation succeeded, and inspect the original declaration and ownership diagnostics.
Generation task skips That source set does not declare graphmaquina-processor on its annotation-processor configuration.
Async graph cannot be built Supply a positive default timeout through the generated set builder.
Watch never triggers Check relationship accessors, owner state, first-match rules, the named edge's guards and whether a peer transition actually committed.
Strict lint reports unclaimed third-party annotations javac's processing lint, which -Xlint:all turns on, warns, in a compilation that runs annotation processors, about the annotations of its sources that no processor claims, the platform's own such as @Override aside, and -Werror turns the warning into an error. GraphMaquina's processor claims only GraphMaquina's own annotations; it is not a wildcard processor for Spring, Jakarta or test annotations, such as JUnit's @Test in a test compilation it runs in. It does not claim javax.annotation.processing.Generated either, so another tool's @Generated that no processor claims gets that warning too; GraphMaquina's companions carry its own @GeneratedCompanion instead. Turn the lint off for that compilation with -Xlint:-processing, or -processing in its -Xlint: list, as the Maven POM does for its test compilation.
Strict lint reports, in generated code, an auxiliary class accessed from outside its own source file A host, or the class it is nested in, is declared in a source file named after another type, and generated code, such as the host's references container, names it from another file. javac's auxiliaryclass lint, which -Xlint:all turns on, warns about that, and -Werror turns the warning into an error. Give that class a file of its own, or turn the lint off with -Xlint:-auxiliaryclass.

For a reproducible issue, include JDK/build-tool versions, relevant build configuration, the minimal graph and binding declarations, the full diagnostic and whether the problem occurs on a clean build. Report issues at GitHub Issues.


Next: Runtime exceptions. Back to the documentation index.