Skip to content

Sprig diagnostic codes (stable) ​

The codes are those of bin/sprig codes (a test keeps the two lists equal); the wording here is edited for reading. Codes never change meaning; new behavior gets a new code. See also sprig explain <code>.

CodeMeaning
SPR-CLI-OPTIONA CLI command is missing a required argument or has an unknown option.
SPR-API-TARGETThe requested Sprig module or project API target cannot be resolved.
SPR-API-MEMBERThe requested --member does not exist on the inspected Sprig declaration.
SPR-CALL-ARITYWrong number of arguments.
SPR-CALL-DUPLICATE-FIELDThe same named field was provided twice.
SPR-CALL-MISSING-FIELDA required field was not provided.
SPR-CALL-NAMED-REQUIREDSprig class and variant constructors require named arguments.
SPR-CALL-POSITIONAL-REQUIREDFunctions and JVM calls require positional arguments.
SPR-CALL-UNKNOWN-FIELDNamed argument does not match any field.
SPR-COLLECTION-IMMUTABLEList/Map are read-only; convert with toMutableList()/toMutableMap().
SPR-FLOW-BREAKbreak is only valid inside a loop.
SPR-FLOW-CATCH-NEVER-THROWNA catch names a checked Java exception that nothing in its try block can throw.
SPR-FLOW-CONTINUEcontinue is only valid inside a loop.
SPR-FLOW-MISSING-RETURNA non-Unit function must return on every path.
SPR-FLOW-RETHROWSrethrows needs a parameter whose function type declares throws Error, and the function may throw nothing of its own.
SPR-FLOW-THROWSA recoverable error must be declared with throws or caught.
SPR-FLOW-THROWS-UNUSEDA function declares a checked Java exception that its body can never throw.
SPR-FLOW-UNREACHABLEStatement follows a statement that always exits.
SPR-CONFORM-EFFECTSA witness method declares checked exceptions the Java interface method does not permit.
SPR-CLASS-ABSTRACTA contract class (a class whose methods have no body) declares fields, mixes methods with and without a body, is generic, or is constructed; a contract is implemented by classes that conform to it.
SPR-CONFORM-MEMBERA class method does not exactly match the Java method it witnesses or overrides, or a required abstract method is missing.
SPR-CONFORM-OVERLOADThe Java interface requires overloaded abstract methods, which Sprig classes cannot represent.
SPR-CONFORM-PARENTThe parent view of a class that extends a Java class only calls inherited methods; it is not a value, has no fields and cannot reach abstract methods.
SPR-CONFORM-SOURCEThe conform source must be a non-generic Sprig class with method bodies, declared in this module; there is no retroactive conformance and a contract never conforms.
SPR-CONFORM-TARGETThe conform target must be an imported public, non-generic, non-sealed Java interface, or with parentheses a public, non-final, non-generic Java class (or the built-in Error, which makes an error class) whose constructor the named fields select.
SPR-JVM-AMBIGUOUSThe Java overload is ambiguous for these argument types.
SPR-JVM-CLASSThe imported Java class could not be loaded, or it lives in the unnamed package.
SPR-JVM-CLASSPATHA --classpath entry is empty, missing, or not a JAR/directory.
SPR-JVM-COMPILEThe generated Java source did not compile; may be a compiler bug.
SPR-JVM-DEPRECATEDWarning, not an error: a Java constructor, method or field annotated @Deprecated is called, accessed or overridden, or a deprecated class is imported. The message names the overload; data.forRemoval says whether it is marked for removal.
SPR-JVM-INTERNALInternal compiler or tooling failure.
SPR-JVM-MEMBERNo Java method/constructor/field matches this call.
SPR-LEX-CHARThe input contains a character outside the Sprig lexer.
SPR-LEX-INDENT-FIRSTThe first code line of a file must start at column 1.
SPR-LEX-INDENT-INCONSISTENTA dedent must return to a previous indentation level.
SPR-LEX-STRINGA string literal is unterminated or contains an invalid escape.
SPR-LEX-TABTabs are forbidden; Sprig indentation uses spaces only.
SPR-LEX-UNCLOSEDA '(' '[' or '{' was opened and never closed.
SPR-LEX-UNMATCHEDA closing delimiter has no matching opener.
SPR-MATCH-DUPLICATEA match branch repeats a case.
SPR-MATCH-ENUM-BINDERPayloadless enum cases cannot bind 'as name'.
SPR-MATCH-INFERENCEAn expression match needs an explicit result type because its branches establish no non-null type.
SPR-MATCH-NONEXHAUSTIVEEvery enum/variant case must have a match branch; there is no default.
SPR-MATCH-RESULTAn expression-match branch has an incompatible result type.
SPR-MATCH-SCRUTINEEmatch requires a non-nullable enum or variant value.
SPR-MATCH-UNKNOWN-CASEThe case name does not exist on the matched type.
SPR-MATCH-WRONG-TYPEA match branch belongs to a different enum/variant.
SPR-MODULE-EXPORTA declaration reexport names an unknown or illegal target, or conflicts with a visible name.
SPR-MODULE-EXPORT-ORDERImports, declaration reexports and ordinary definitions are out of order.
SPR-NAME-DUPLICATETwo declarations share one name in one namespace.
SPR-NAME-DUPLICATE-MEMBERA class/variant declares the same member twice.
SPR-NAME-FIELD-SHADOWA parameter/local cannot shadow a current-class field.
SPR-NAME-IMPORTAn imported file or class cannot be resolved.
SPR-NAME-IMPORT-CYCLESprig modules form an import cycle.
SPR-NAME-LET-ASSIGNlet bindings and let fields cannot be reassigned.
SPR-NAME-FORWARD-REFERENCETop-level code uses a top-level binding before its declaration runs.
SPR-NAME-NOT-A-VALUEA type or module name was used as a value.
SPR-NAME-UNRESOLVEDA name has no declaration in the current scope chain.
SPR-NUM-RANGEA numeric literal is outside its target range or underflows to zero.
SPR-NUM-CONVERSIONAn implicit numeric conversion risks precision or range loss, or a Float/Float32 is a Map key, also through generic code (reported at the use that gives the type argument).
SPR-NUM-DIVISIONInteger/BigInt / would truncate, or Decimal / lacks a rounding policy.
SPR-NUM-MIXEDA numeric operator cannot implicitly mix these numeric families.
SPR-RUNTIME-ERRORUncaught Sprig Error value at runtime; the wrapped message, origin data and source range are reported. The range is the innermost line in the program's own modules: a failure inside an @std function points at the line that called it.
SPR-WRAP-CHECKGenerated Java-to-Sprig wrapper source failed Sprig checking or formatting.
SPR-RUNTIME-EXCEPTIONUncaught JVM exception at runtime, wrapped to a Sprig-level message with a source range (the innermost line in the program's own modules, as for SPR-RUNTIME-ERROR); run --stacktrace restores the raw JVM stack.
SPR-BUNDLE-TOOLSsprig build --bundle needs jdeps and jlink from a full JDK; the Java installation in use has none (a JRE).
SPR-BUNDLE-JDEPSjdeps could not analyze the bundle's JARs to find the Java modules the program needs.
SPR-BUNDLE-LAYOUTThe Java installation or the classpath has a layout the bundle cannot use: no packaged modules and no linkable runtime for jlink, a jlink failure, a previous bundle that cannot be removed, or a classpath entry that does not exist.
SPR-PROGRAM-EXITThe Sprig program exited with a non-zero process status.
SPR-SYNTAX-ERRORThe token sequence does not match the Sprig grammar.
SPR-TYPE-ASSIGNAssignment value does not match the target type.
SPR-TYPE-FUNCTION-ARITYFunction types and lambdas support zero to three explicitly typed parameters.
SPR-TYPE-CALLABLE-THROWSA function value's throws clause does not fit where it is used; only fn(...) -> R throws Error exists, and it is not accepted where a function type without throws is expected.
SPR-TYPE-CAPTUREA lambda captures a var local; copy it into a let binding first.
SPR-TYPE-CONDITIONConditions must be Bool; Sprig has no truthiness.
SPR-TYPE-INFERThe type cannot be inferred without an annotation.
SPR-TYPE-MISMATCHExpected and actual types are not compatible.
SPR-TYPE-NOT-CALLABLEThe callee is not callable (or a method name was used as a value).
SPR-TYPE-NULLnull is only assignable to an explicit nullable type T?.
SPR-TYPE-NULLABLEA possibly-null value is used where non-null is required, including a T? joined into a String; check for null first.
SPR-TYPE-OPERANDOperator or method is not defined for this operand type.
SPR-TYPE-RETURNReturned value does not match the declared return type.
SPR-TYPE-UNITUnit is only a function/method result; it cannot be a field, parameter, collection element, or ordinary value.
SPR-TYPE-GENERIC-ARITYA generic declaration was used with the wrong number of type arguments (supply every parameter in declaration order).
SPR-TYPE-GENERIC-ARGS-REQUIREDA generic call or constructor needs written [Type] arguments: its arguments do not say what a type parameter is, or two of them disagree.
SPR-TYPE-GENERIC-NULLABLEThis type parameter is used with ? in the declaration, so its argument must be non-nullable.
SPR-GENERIC-CONSTRAINTA requires clause names an unknown capability, or a contract or class in place of one (a contract is a type, never a bound), or is misplaced, or a type argument is not Comparable where the callee requires it.
SPR-PROJECT-MANIFESTsprig.toml is missing, malformed, or lacks a required field.
SPR-PROJECT-ENTRYThe project entry point is missing or the named --bin is unknown.
SPR-PROJECT-UNSUPPORTEDThe project or a dependency needs project features or a language version this compiler does not support.
SPR-PROJECT-LOCK-MISSINGThis project has no sprig.lock; run sprig resolve.
SPR-PROJECT-LOCK-STALECompiler identity, sprig.toml or a dependency manifest differs from sprig.lock; run sprig resolve.
SPR-PROJECT-LOCK-SCHEMAThe lockfile schema version is not supported.
SPR-PROJECT-NOT-EXPORTEDA module imported from a dependency is not in its exports.
SPR-DEP-CYCLESprig project dependencies form a cycle.
SPR-DEP-NOT-FOUNDA declared Sprig dependency or module cannot be found.
SPR-DEP-GITA Git dependency operation failed. Cache-lock contention waits up to five seconds, then asks the user to retry; it never steals a lock.
SPR-DEP-OFFLINEA required dependency resource is missing from the cache in offline mode.
SPR-DEP-REGISTRYA package registry could not be read, or does not list the requested package or version. sprig search shows what a registry lists.
SPR-DEP-CHECKSUMLocked dependency bytes do not match SHA-256; corrupted cache is rejected.
SPR-DEP-MAVENA JVM (Maven) dependency operation failed.

Optional structured fields ​

Diagnostic JSON keeps the stable fields (code, phase, severity, uri, range, message, related, suggestedEdits) and may add optional fields:

FieldMeaning
expectedType / actualTypeRendered types involved in a mismatch.
hintOne short human instruction.
exampleThe URL of a documentation page with a worked example of the repair. Text output shows it as an example: line under the hint, and the language server sends it as the diagnostic's codeDescription.href.
relatedHelpHelp topic accepted by sprig help <topic>.
repair{ "kind": ..., "machineApplicable": bool } repair strategy.

suggestedEdits is always present. It is usually empty; when the hint names one mechanical rewrite, the list holds it as { "range": {start, end}, "newText": "...", "description": "..." } with the same zero-based positions as range, a zero-length range for an insertion, and newText replacing exactly that range. Applying an edit moves the program past the diagnostic; whether it is what the author meant (adding throws Error to a function, say) is still theirs to judge. Edits exist today for a missing @std import, an undeclared throws, positional constructor arguments, else if, and the removed conversions Int.toFloat() and Float.toInt() (rewritten to toFloatExact() and toIntExact()). In an editor, sprig lsp offers the same edits as quick fixes; see language server.

machineApplicable is true only for a correction that is semantics-preserving and unambiguous. When it is false, treat repair.kind as a strategy, not a patch: for example a nullable value needs an explicit narrow/handle decision, which is business logic the compiler must not invent. sprig explain <CODE> --json returns the same repair object plus causes, safe fixes and examples.

Syntax errors ​

  • SPR-SYNTAX-ERROR reports layout problems in source-level terms, such as an unexpected indentation or a missing indented block after a header (else:, if ...:, func ...:). Parser recovery does not expose synthetic INDENT, DEDENT or end-of-file tokens as user-facing wording (source text quoted in a message, such as an identifier MAX_INDENT, is never rewritten), and redundant end-of-file errors after a missing block are suppressed.

Declaration facade errors ​

  • SPR-MODULE-EXPORT: unknown/illegal target or duplicate/colliding visible name; includes origin names.
  • SPR-MODULE-EXPORT-ORDER: imports, exports, declarations/statements must appear in that order.
  • Existing SPR-NAME-IMPORT-CYCLE also rejects reexport chains containing a cycle.

Function signatures ​

  • SPR-SYNTAX-ERROR reports a throws clause without a declared result type with explicit guidance (-> Unit throws Error), a hint to add the result type and the functions help topic.

Expression match results ​

  • SPR-MATCH-RESULT: incompatible branch result; expected/actual types and match repair guidance.
  • SPR-MATCH-INFERENCE: no non-null type can be inferred; annotate explicitly.
  • Existing SPR-MATCH-*, null/numeric/capture/effect diagnostics also apply.
  • SPR-SYNTAX-ERROR rejects empty/multi-statement/declaration branches, with statement-match guidance where the parser retains branch context.
  • SPR-TYPE-UNIT rejects side-effect-only expression matches.

If expression results ​

  • SPR-SYNTAX-ERROR reports, each once and at the place to fix: a missing else ("An if expression needs an else branch"), a branch value on the header's line, a branch with several lines or a statement, an if expression inside parentheses, brackets or braces, an if expression used as an operand, and Python's a if c else b and C's c ? a : b, with the if expression as the hint. else if keeps its mechanical rewrite to elif. An if guard on a match case (case X as c if cond:) and an if filter on a for loop get a hint to test the condition inside the body. A grammar predicate's text is never a message: a statement that goes on past its end reads "Expected the end of the line".
  • SPR-TYPE-CONDITION: a condition that is not Bool.
  • SPR-TYPE-MISMATCH ("Type mismatch in if branch result") and the numeric conversion codes: a branch incompatible with the expected type or with the first non-null branch.
  • SPR-TYPE-INFER: every branch is null and nothing gives the type.
  • SPR-TYPE-UNIT: a branch without a value; use an if statement.

Java boundary recipes ​

A diagnostic about a Java call for which the checker knows the class and the member carries an example: the recipe of the Java interop cookbook that shows this kind of mismatch before and after.

DiagnosticRecipe
SPR-JVM-MEMBER, SPR-JVM-AMBIGUOUS#overloads; #collections when an argument is a Sprig list or map and a candidate takes the Java collection
SPR-TYPE-CALLABLE-THROWS for a Java parameter#callbacks
SPR-TYPE-NULLABLE for an argument of a Java call#nullable

SPR-JVM-MEMBER and SPR-JVM-AMBIGUOUS had no hint for such a call; the hint is now the command that lists the real signatures, for example Run sprig api java.util.Collections --member sort to see the signatures this call can match. The other hints, the codes, the candidate list in data and the programs the compiler accepts are unchanged. Neither the hint nor the example chooses an overload.

Sprig is licensed under Apache-2.0 · v0.7.1-beta.1 published as a prerelease