Error messages

The messages the runner reports when a configuration, a plug or a run is wrong, and what each means.

Messages are grouped by when they appear. Text in <angle brackets> varies.

When the configuration is read

These messages come from blaise-agent listen before it waits for sessions, and list every problem found.

Message	Meaning and fix
`<file>: file not found (included from <chain>)`	An `!include` names a file that does not exist. The path is relative to the file that contains it.
`include cycle: <a> -> <b> -> <a>`	Files include each other. Break the cycle.
`<file>:<line>:<column>: <YAML problem>`	The YAML is invalid. A hint is added for a scoped package name that needs quotes.
`<file>: the file must contain a mapping at the top level`	`blaise.yml` must be a mapping with `version` and the other keys.
`<path>: <schema problem>`	A key is unknown, of the wrong type, or out of range. See Configuration keys.
`<include chain>: !include cannot be used as a key (!include <ref>)`	`!include` takes the place of a value, not of a key.
`<include chain>: the target of a merge must be a mapping (!include <ref>)`	`<<: !include` must include a mapping.
`setup[<n>].use: expressions are not allowed in use; plugs are resolved at startup`	`use:` is a literal: plugs are loaded before any run exists.
`setup[<n>].id: duplicate id "<id>" (also on setup[<m>])`	Ids identify plugs and must be unique.
`setup[<n>].with: setup.<id> refers to a plug id that is not declared by an earlier entry`	An expression reads the outputs of a plug that comes later or does not exist.
`<path>: <expression problem>`	A `${{ }}` expression does not parse, or uses a context or function that is not available there. See Expressions.

Message	Meaning and fix
`plug <n>: <use> is not bundled with the runner and @blaiseagent/plugs-<name> is not installed; add it to the project's dependencies`	A `blaise:` plug that ships in its own package. Install the package.
`plug <n>: <use> is not installed; add it to the project's dependencies`	A package name that does not resolve.
`plug <n>: <use>: file not found (<path>)`	A relative path that does not exist.
`plug <n>: <use>: invalid name; expected lowercase words separated by "-" and "/"`	A `blaise:` name with other characters.
`plug <n>: <use> failed to load: <error>`	The module threw when imported.
`plug <n>: <use> does not default-export a plug; wrap it in definePlug()`	The default export is not the result of `definePlug`.
`plug <n>: <use> was built for plug API <a>.x; this runner implements <b>.x`	Upgrade the plug or the runner so the major versions match.
`plug <n> (<name>) keeps persisted state and needs an id`	Give the entry an `id`.
`plug <n> "<id>" (<use>): invalid with: <problem>`	A literal `with:` fails the plug's `inputs` schema. Inputs with expressions are checked when the plug runs.
`<plug> is not resumable; set the agent's idle policy to "end" in Blaise, or remove the plug`	The agent pauses idle sessions and this plug cannot resume. See Resolving plugs.

These fail the run. The plug is named by its position, id and name.

Message	Meaning and fix
`<plug>: invalid inputs: <problem>`	`with:` after expression evaluation fails the plug's `inputs` schema.
`<plug>: <expression problem>`	An expression failed when evaluated.
`<plug>: onLoad failed: <error>`	`onLoad` threw.
`<plug>: next() was called twice`	A handler called `next()` more than once.
`<plug> returned without calling next()`	A handler returned without calling `next()`. Inner plugs and the agent never ran.
`ctx.agent... cannot be changed after next() was called`	`ctx.agent` is writable only before `next()`.
`<plug> changed a <direction> <method> message into …; only its params can change`	An `onMessage` handler passed on a message with another method or direction.
`<plug>: refusing to store an invalid value: <problem>`	`ctx.persisted.set` was given a value that fails the `persisted` schema.
`this plug did not declare a persisted schema, so it has no persisted state`	A plug without `persisted` called `ctx.persisted.set` or `clear`.
`<plug>: stored state no longer validates and the plug has no onMigrate: <problem>`	Add an `onMigrate`. See Store state and migrate it.
`<plug>: onMigrate threw: <error>`	The migration failed.
`<plug>: onMigrate returned a value that does not validate: <problem>`	The migration produced a value of the wrong shape.

These come from the run's connection to the agent and to Blaise:

Message	Meaning and fix
`malformed <method> params: <problem>`	A message of a protocol method carries parameters that do not match the protocol. A request is answered with an invalid-params error; a notification is dropped and logged. Plugs never see it.
`malformed permission option`	The agent's permission request has an option without a string id or name.
`Lost contact with Blaise: <n> heartbeats in a row failed`	The run could not reach Blaise for about 30 minutes (90 heartbeats). It stops; Blaise recovers the session. Check the runner's network.
`The persisted state of "<id>" cannot be read`	A stored record cannot be decrypted, because the server's key changed or the record was altered. The run fails rather than provision again.
`The run has finished and can no longer change plug state`	A persisted-state write arrived after the run ended. It is rejected.
`Blaise asked to pause the session, but a plug cannot resume it` (warning)	Blaise decided to pause and a plug is not resumable, so a later resume may fail. The warning names the plugs.

A command that a plug runs on a host and that exits non-zero is reported as <command> exited with <code>: <stderr>.