Troubleshoot a mod

When a mod does nothing, shows nothing, or disappears mid-session, the cause is almost always one of a few things: it is not on, its manifest is invalid, its program cannot be found, or it is sending messages Syntic Code refuses. This page goes through each, starting from the quickest checks.

Start with `syntic mod list`

syntic mod list

This one command answers most questions:

What you see	Meaning
`No mods installed. A mod is a folder with a mod.json in …`	Syntic Code found no valid mod folder at that path.
The mod is not listed	Its folder name is not a valid mod name, or the folder has no `mod.json`.
`[off]`	Installed but not switched on. Run `syntic mod enable <name>`.
`[on]`	Switched on. It starts with your next interactive session.
`[broken]` plus a reason	The manifest could not be read. The reason is on the next line.
`granted: …`	The permissions the mod has.
`now also asks for: …`	An update added permissions you have not granted. They stay off until you enable the mod again.
`(SYNTIC_DISABLE_MODS is set: no mod starts this time)`	The kill switch is on in this shell.

The mod does not start

Work through these in order.

Is it on? syntic mod list must show [on].
Is this an interactive session? Mods never start in syntic -p runs.
Is the kill switch set? If SYNTIC_DISABLE_MODS is set to anything other than empty, 0, false, no or off, no mod starts. Check with echo "$SYNTIC_DISABLE_MODS".
Did you start a new session? Enabling, disabling or editing a mod has no effect on a session that is already running.
Is it in the right folder? Mods are read from ~/.syntic/mods/, or from mods/ under SYNTIC_CONFIG_DIR when that is set to an absolute path. A .syntic/mods/ folder inside a project is never read.
Did a start-up warning appear? If the program could not be run, a warning line in the conversation reads Mod `<name>` did not start: … with the reason.

The mod shows as broken

The reason line tells you what to fix. Typical reasons:

Reason	Fix
`mod.json is not valid`	The file is not valid JSON, has a key Syntic Code does not know, or a value of the wrong type. Unknown keys are not ignored.
name `…` must be 1-40 lowercase letters, digits or dashes	Rename to lowercase letters, digits and dashes, not starting with a dash.
mod.json names `a` but the folder is `b`	Make the folder name and `name` match exactly.
`command is empty`	Give `command` a program, as a string or a non-empty array.
unknown event `…`	Use only `session.start`, `session.end`, `turn.start`, `turn.end`, `mode.change`.
unknown ui slot `…` (status, band or pane)	Use only those three slot names.
unknown permission `…` (notes or session.read)	Use only those two permission names.

`syntic mod enable` fails

Message	Cause
no mod named `…` in …	No valid folder with that name under the mods folder.
mod `…` is broken: …	Fix the manifest first (see above).
command `…` leaves the mod folder	The command path uses `..`, or is a symlink that points outside the mod folder. Keep the program inside the folder, or use an absolute path.
command `…` not found in the mod folder	The relative path in `command` does not exist.
program `…` not found on PATH	A bare program name such as `python3` could not be found on the cleaned `PATH`. Folders inside the opened project, relative folders and missing folders are removed from it. Use an absolute path to the program, or install it in a standard location.

The mod starts and then stops

When a running mod ends, Syntic Code clears everything it drew and adds a warning line to the conversation. The wording tells you what happened:

Notice	Cause
Mod `<name>` exited; its display was cleared	The program ended on its own with exit code 0. Usually it stopped reading input too early, or its loop ended on an unexpected message.
Mod `<name>` exited with code N; its display was cleared	The program crashed or quit with an error. Run it by hand to see its error output (standard error is discarded in a session).
Mod `<name>` stopped; its display was cleared	The program was killed by a signal.
Mod `<name>` stopped: too many messages it is not allowed to send	It sent more than 20 bad lines. See below.

A stopped mod stays stopped until the next session.

Too many bad lines

Each of these counts as one bad line:

output that is not JSON, such as a debug print or a shell prompt;
a JSON object with an unknown type;
a line over 64 KB, or one that is not valid UTF-8;
a draw to a slot not listed in ui;
a call to an unknown method or one you were not granted.

Fix: log to a file in $SYNTIC_MOD_DATA instead of standard output, add any slot you draw in to ui, and check granted in the hello message before making calls. To find the offending lines, run the program by hand as shown in Test a mod.

Nothing is drawn

Symptom	Likely cause
Nothing appears at all	Output is buffered. Flush after every line.
The pane never appears	The conversation area is narrower than 90 columns, or there is not enough height left for a three-row box.
Band rows are missing	The terminal is short; at least six rows are always kept for the conversation. Only two band rows per mod are ever shown.
Text ends in `…`	It was longer than the slot’s limit and was cut.
Odd characters like `[31m` appear	You sent terminal color codes. The escape byte is removed and the rest is shown as text. Send plain text.
An item flickers or goes blank	Each `draw` replaces the slot, and a draw with no text clears it. Check you always send the full content.

Events are missing

The event must be in events in mod.json. Adding it takes effect from the next session.
A subscribe message replaces the subscription. If you sent a short list, you will only get those events.
mode.change is not sent for the mode a session starts in.
If your program stops reading standard input, its queue of 64 messages fills and new events are dropped. Read input continuously and do slow work elsewhere.

Notes are missing

The mod needs the notes permission, and it must be granted. A permission added by an update stays off until syntic mod enable is run again.
Only 5 notes per minute per mod are shown. Extra calls get an error result.
A note that is empty after cleaning is refused.

Turn every mod off

To rule out mods entirely while you investigate something else, start a session with the kill switch:

SYNTIC_DISABLE_MODS=1 syntic

Or switch off one mod at a time with syntic mod disable <name>.

The file that records which mods are on and what they were granted is ~/.syntic/mods.json. You can read it to check state, but use syntic mod enable and disable to change it. Hand-editing it cannot grant a permission the manifest does not ask for.

Next steps

Test a mod: reproduce a problem outside a session.
Mod API: the full message list and limits.
mod.json reference: every manifest field.

Test a mod Mods for administrators