Skip to content

Appendix B. Error codes and where to read about them ​

Every diagnostic from the compiler carries a fixed error code that starts with SPR-. A code's meaning never changes: new behavior gets a new code. This appendix lists the compiler's current 100 codes by category, one line each; the codes and the count change as the compiler does, so sprig codes always has the latest list.

B.1 How to read an error code ​

The first line of an error has four parts:

text
SPR-NUM-DIVISION [TYPE] main.spr:2:7: Integer / would truncate; use a.divTrunc(b), or convert both operands explicitly (expected explicit division, actual Int / Int)
  • SPR-NUM-DIVISION: the error code, stable;
  • [TYPE]: the phase that failed (lexing LEX, syntax SYNTAX, names NAME, types TYPE, flow FLOW, runtime RUNTIME, ...);
  • main.spr:2:7: file, line and column (counting from 1);
  • then the message; a hint: line, when there is one, is the suggestion editors use for quick fixes too.

For the full explanation, give the code to sprig explain:

text
$ sprig explain SPR-NUM-DIVISION
SPR-NUM-DIVISION: Integer / is rejected; use divTrunc for deliberate truncation or explicit Float/Decimal arithmetic.
Why it matters: Integer / silently truncates in many languages; Sprig requires the intent to be explicit.
Common causes:
  - Integer division was written with / instead of divTrunc.
Safe fixes:
  - Use value.divTrunc(divisor) only when truncation is intended.
  - Convert to Float or Decimal when fractional arithmetic is intended.
Good:
  let q = (7).divTrunc(2)
Bad:
  let q = 7 / 2

sprig explain <CODE> --json gives the same information, plus the related help topic (relatedHelp, which you can pass straight to sprig help) and the repair suggestion; that form is meant for editors and AI assistants. sprig check file.spr --json prints every diagnostic from one check as structured JSON.

The tables below group the codes by prefix. Each line says only when the code appears; use sprig explain for how to fix it and why it is designed that way.

B.2 Tooling and the command line ​

CodeWhen it appears
SPR-API-MEMBERThe requested --member does not exist on the inspected Sprig declaration.
SPR-API-TARGETsprig api cannot resolve the Sprig module or project to inspect.
SPR-BUNDLE-JDEPSjdeps cannot analyze the bundled 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 linkable runtime, a jlink failure, or an old bundle that cannot be removed.
SPR-BUNDLE-TOOLSbuild --bundle needs jdeps and jlink from a full JDK, but the Java installation in use is a JRE.
SPR-CLI-OPTIONA command line is missing a required argument, or has an unknown option.
SPR-WRAP-CHECKThe generated Java wrapper source from sprig wrap failed Sprig checking or formatting.

B.3 Lexing and syntax ​

CodeWhen it appears
SPR-LEX-CHARThe input contains a character the Sprig lexer does not know.
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 not allowed; indentation uses spaces only.
SPR-LEX-UNCLOSEDA (, [ or { was opened and never closed.
SPR-LEX-UNMATCHEDA closing bracket has no matching opener.
SPR-SYNTAX-ERRORThe token sequence does not match the Sprig grammar.

B.4 Names, modules and exports ​

CodeWhen it appears
SPR-MODULE-EXPORTThe target of an export is unknown, not public, or collides with a visible name.
SPR-MODULE-EXPORT-ORDERThe order must be imports, exports, then ordinary declarations and statements.
SPR-NAME-DUPLICATETwo declarations share one name in one namespace.
SPR-NAME-DUPLICATE-MEMBERA class or variant declares the same member twice.
SPR-NAME-FIELD-SHADOWA parameter or local cannot share the name of a field of the current class.
SPR-NAME-FORWARD-REFERENCETop-level code uses a top-level binding that only runs below it.
SPR-NAME-IMPORTAn imported file or class cannot be resolved.
SPR-NAME-IMPORT-CYCLESprig modules import each other in a cycle.
SPR-NAME-LET-ASSIGNA let binding or let field cannot be reassigned.
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.

B.5 Calls and construction ​

CodeWhen it appears
SPR-CALL-ARITYThe number of arguments is wrong.
SPR-CALL-DUPLICATE-FIELDThe same named field was given twice.
SPR-CALL-MISSING-FIELDA required field was not given.
SPR-CALL-NAMED-REQUIREDSprig class and variant constructors require named arguments.
SPR-CALL-POSITIONAL-REQUIREDOrdinary functions and JVM calls require positional arguments.
SPR-CALL-UNKNOWN-FIELDA named argument matches no field.

B.6 Types and generics ​

CodeWhen it appears
SPR-GENERIC-CONSTRAINTA requires clause names an unknown capability, a contract or class instead of a capability, is in the wrong place, or a type argument is not Comparable where the callee requires it.
SPR-TYPE-ASSIGNThe assigned value does not match the target type.
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 as a type without throws.
SPR-TYPE-CAPTUREA lambda captures a var local; copy it into a let first.
SPR-TYPE-CONDITIONA condition must be Bool; Sprig has no truthiness.
SPR-TYPE-FUNCTION-ARITYFunction types and lambdas support zero to three explicitly typed parameters.
SPR-TYPE-GENERIC-ARGS-REQUIREDA generic call or constructor needs written [Type] arguments: the arguments do not say what a type parameter is, or two of them disagree.
SPR-TYPE-GENERIC-ARITYA generic declaration was used with the wrong number of type arguments; supply every parameter in declaration order.
SPR-TYPE-GENERIC-NULLABLEThis type parameter is used with ? in the declaration, so its argument must be non-nullable.
SPR-TYPE-INFERThe type cannot be inferred without an annotation.
SPR-TYPE-MISMATCHThe expected 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 value that may be null was used where a non-null value is required; check for null first.
SPR-TYPE-OPERANDThe operator or method is not defined for this operand type.
SPR-TYPE-RETURNThe returned value does not match the declared result type.
SPR-TYPE-UNITUnit is only valid as a function or method result; it cannot be a field, parameter, collection element or ordinary value.

B.7 Control flow and runtime ​

CodeWhen it appears
SPR-FLOW-BREAKbreak is only valid inside a loop.
SPR-FLOW-CATCH-NEVER-THROWNA catch names a checked Java exception that nothing in the 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 on the spot.
SPR-FLOW-THROWS-UNUSEDA function declares a checked Java exception that its body can never throw.
SPR-FLOW-UNREACHABLEA statement follows a statement that always exits.
SPR-PROGRAM-EXITThe Sprig program exited with a non-zero status.
SPR-RUNTIME-ERRORAn uncaught Sprig Error value at runtime; the message is the content of the Error.
SPR-RUNTIME-EXCEPTIONAn uncaught JVM exception at runtime, wrapped with a Sprig source position; --stacktrace shows the full JVM stack.

B.8 Numbers ​

CodeWhen it appears
SPR-NUM-CONVERSIONAn implicit numeric conversion could lose precision or range; use an explicit method.
SPR-NUM-DIVISIONInteger / is rejected; for deliberate truncation use divTrunc, and for Decimal use divide.
SPR-NUM-MIXEDA binary operation mixes integer and floating-point values, or binary floating-point and decimal.
SPR-NUM-RANGEA numeric literal is outside the target range, or underflows to zero.

B.9 Classes, contracts and collections ​

CodeWhen it appears
SPR-CLASS-ABSTRACTA contract class (a class whose methods have no bodies) declares fields, mixes methods with and without bodies, is generic, or is constructed.
SPR-COLLECTION-IMMUTABLEThe List/Map is read-only; convert with toMutableList()/toMutableMap() first.
SPR-CONFORM-EFFECTSA witness method declares checked exceptions the Java interface method does not allow.
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-PARENTA parent view (as NAME) only calls inherited methods; it is not a value, has no fields, and cannot call abstract methods.
SPR-CONFORM-SOURCEThe left side of conform must be a non-generic Sprig class with method bodies declared in this module; there is no retroactive conformance, and a contract cannot conform.
SPR-CONFORM-TARGETThe target of conform must be an imported public, non-generic, non-sealed Java interface; with parentheses it is a public, non-final, non-generic Java class (the built-in Error is one of these).

B.10 Enums, variants and match ​

CodeWhen it appears
SPR-MATCH-DUPLICATEA match branch repeats a case.
SPR-MATCH-ENUM-BINDERA payloadless enum case cannot bind as name.
SPR-MATCH-INFERENCEAn expression match cannot settle on a non-null result type without an explicit annotation.
SPR-MATCH-NONEXHAUSTIVEEvery enum/variant case needs a branch; there is no default.
SPR-MATCH-RESULTAn expression match branch's result type disagrees with the expected type (or the first non-null branch).
SPR-MATCH-SCRUTINEEmatch only matches a non-nullable enum or variant value.
SPR-MATCH-UNKNOWN-CASEThe case name does not exist on the matched type.
SPR-MATCH-WRONG-TYPEA branch belongs to a different enum/variant.

B.11 Java interop ​

CodeWhen it appears
SPR-JVM-AMBIGUOUSThe Java overload is ambiguous for these argument types.
SPR-JVM-CLASSThe imported Java class cannot be loaded, or it lives in the unnamed package.
SPR-JVM-CLASSPATHA --classpath entry is missing, empty, or not a JAR or directory.
SPR-JVM-COMPILEThe generated Java source did not compile; this may be a compiler bug.
SPR-JVM-INTERNALInternal compiler or tooling failure.
SPR-JVM-MEMBERNo Java method, constructor or field matches this call.

B.12 Projects and dependencies ​

CodeWhen it appears
SPR-DEP-CHECKSUMA locked dependency's bytes differ from its recorded SHA-256; do not use the corrupted cache entry.
SPR-DEP-CYCLESprig project dependencies form a cycle.
SPR-DEP-GITA Git dependency operation failed: missing git, remote, ref or revision.
SPR-DEP-MAVENA JVM (Maven) dependency operation failed.
SPR-DEP-NOT-FOUNDA declared Sprig dependency or module cannot be found.
SPR-DEP-OFFLINEA dependency resource that offline mode needs is not in the cache.
SPR-DEP-REGISTRYA package registry cannot be read, or does not list the requested package or version.
SPR-PROJECT-ENTRYThe project entry point does not exist, or the name given to --bin is unknown.
SPR-PROJECT-LOCK-MISSINGThe project has no sprig.lock; run sprig resolve first.
SPR-PROJECT-LOCK-SCHEMAThe lockfile schema version is not supported by this compiler.
SPR-PROJECT-LOCK-STALEThe compiler identity, sprig.toml, or a dependency manifest differs from the lock; run resolve again.
SPR-PROJECT-MANIFESTsprig.toml is missing, malformed, or lacks a required field.
SPR-PROJECT-NOT-EXPORTEDA module imported from a dependency is not exported by that dependency.
SPR-PROJECT-UNSUPPORTEDThe project or a dependency needs project features or a language version this compiler does not support.

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