---
title: "Diagnostics and troubleshooting"
version: "2.0.4"
tag: "v2.0.4"
commit: "02030bc920623059a212df5dee2957eb2ab2416f"
canonical: https://graphmaquina.dev/v/latest/diagnostics
---

# 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](https://graphmaquina.dev/v/2.0.4/runtime-exceptions.md).

## Contents

- [Graph and declaration diagnostics](#graph-and-declaration-diagnostics)
- [Generation and typed binding diagnostics](#generation-and-typed-binding-diagnostics)
- [Common build problems](#common-build-problems)

## 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](https://graphmaquina.dev/v/2.0.4/build-troubleshooting.md#processor-output-failures-sg599). |
| `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](https://graphmaquina.dev/v/2.0.4/installation.md#pomxml) 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](https://github.com/graphmaquina/graphmaquina/issues).

---

Next: [Runtime exceptions](https://graphmaquina.dev/v/2.0.4/runtime-exceptions.md). Back to the [documentation index](https://graphmaquina.dev/v/2.0.4/index.md).
