Troubleshooting

Troubleshooting

First distinguish a syntax error, a semantic error, an unsupported output and an unfinished implementation. Their remedies are different.

Missing public capability

Deliberately invalid example:

main.expec

concept StoreGame {
  public saveGame
  capability save(snapshot: Text) returns Nothing
}

Declare saveGame or change the public list to save. A public name does not declare the capability it names. The parser can read this source, but meaning validation rejects it.

Other common errors

Observation	Check
Unknown type/name	Declare it in scope or import it; spelling and case must match
Unknown package requirement	Declare its alias and required phase in expec.json; installation is separate
Syntax error between members	Put siblings on separate lines; remove semicolon separators
Syntax error inside a list/record value	Use commas; a newline is not a comma
Unknown field	Check the receiver's declared record type and field spelling
Optional value rejected	Optional is not automatically unwrapped into a required value
Wrong nominal record	Identical fields do not make different named records interchangeable
Missing/extra call argument	Match the signature; only declared defaults permit omission
Required argument after default	Put required parameters first
Unavailable result	The contextual result exists in a value-returning callable's ensures
Invalid public type exposure	Keep local types out of public parameters/results/failures
Invalid error code	Use a required, nondefaulted closed Text-literal code set
Invalid scenario role/order	Use setup in given, action/callable in when, check/Boolean/prose in then
Missing captured result	Declare a value result; Nothing cannot be captured
Composition problem	Supply the actual companion files and check their own imports/cycles
Unsupported mapping	Select a supported construct/profile; compilation alone does not promise native generation
Generated driver throws unfinished	Implement the driver against the real application
Prose expectation remains unfinished	Add an executable observation/check or retain the obligation honestly
Stale test selection/evidence	Build the current specification; do not silently reuse unrelated assertions
Preservation conflict	Inspect the diagnostic and deliberate identity choice before writing again

A missing declaration really is missing

Deliberately invalid example:

main.expec

concept StoreGame {
  public save
  capability save(snapshot: PlayerStateSnapshot) returns Nothing
}

The type needs a declaration or import. depends on PlayerStateSnapshot alone would not create it either.

A semicolon is not a separator

Deliberately invalid example:

main.expec

type Cart {
  count: Number; title: Text
}

Use a newline between the two fields. To continue a value across lines, use the relevant parentheses, list or record delimiters.

A fixture does not inherit type defaults

Deliberately invalid example:

main.expec

type Book {
  title: Text
  available: Boolean = true
}
examples {
  fixture dune: Book = Book { title: "Dune" }
}

Fixture data must explicitly supply the nonoptional available field. Add available: true to the record value. The type's default does not act as fixture setup; this is reported as missing-fixture-data. Fixtures can omit optional fields, and runtime calls are not permitted in fixture data.

Check succeeds, but the application is unfinished

That can be correct. Checking establishes type/name/contract consistency, not a real runtime implementation. Read the shopping example and implement its driver against an actual application. Keep the expected value independent, make the implementation wrong, observe failure, then repair it without changing the expectation.

Related: Keyword index · Lexical syntax · Output support