Troubleshooting

Exit codes

0

The command completed.

2

The command has invalid syntax.

3

The local source or tests.toml source is invalid.

4

The manifest or package validation failed.

5

The worker for the current runtime is unavailable.

6

One or more test scenarios failed.

7

The output write failed.

8

The project operation was rejected.

130

The author operation was canceled.

Manifest and package errors

1. Read the first reported path and error code.
2. Fix the field or file at that path.
3. Run blokebot-plugin generate again.
4. Run blokebot-plugin validate again.

• Check the exact TOML field name and value kind.
• Check each declared identifier and reference.
• Check each package path and letter case.
• Check each asset and payload.
• Check each top-level target.
• Check that no link or undeclared file exists in the package.

LuaLS

1. Run blokebot-plugin generate from the plugin root.
2. Check that .luarc.json lists ./.blokebot/lua/5.4/v1.
3. Restart the Lua language server for the workspace.
4. If generation rejects the project, fix each plugin.toml error.

Host call errors

• Declare the host module and supported API range in plugin.toml.
• Call the function only from a supported context.
• Use the generated parameter types and limits.
• Use context.current. Do not supply a host or feature identity.
• Use the typed failure code and safe message as the result.

Page action errors

• Set the action kind to page.
• Match the field IDs in the generated form.
• Match the required flags and value kinds in the generated form.
• Send only the declared fields.
• Use a new message ID for each embedded page action attempt.
• If the session expires or the plugin generation changes, reload the page.

Runtime states

Disabled

After the required settings and template graph are valid, enable the feature.

EnabledDegraded

Check the declared Twitch scopes and EventSub readiness for work that requires Twitch.

WorkerExited

Read the worker diagnostic. One automatic recovery attempt can run before the installation enters a fault state.

MigrationFailed

Correct the selected package or migration. Start a new administrator action. Old code does not resume.

RecoveryPackageUnavailable

Restore the exact selected package through an administrator install or update action.

Diagnostic evidence

• Record the author command and its exit code.
• Record the manifest path and validation error code.
• Record the installation state and administrator action.
• Record the safe failure code.
• Record the feature readiness and required Twitch state.
• Remove protected values and tokens from the evidence.
• Remove request bodies and private database contents from the evidence.