Troubleshoot plugins

Find the symptom you see, then work through the checks under it. Most plugin problems come down to one of three things: the catalog could not be read, the plugin did not install, or it installed but did not load. How plugins load explains the stages behind these checks.

First, gather facts

These commands answer most questions without guessing:

syntic plugin list                 # what is installed, its version and on/off state
syntic plugin marketplace list     # which catalogs are saved and how many plugins each lists
syntic plugin details <plugin>     # what a plugin brings and what it costs per request
syntic doctor                      # policy in force and plugins left off by dependencies

Add --json to any syntic plugin command for output you can paste into a bug report or feed to a script.

For deeper logs, start a session with --debug (optionally --debug-file <path> to keep them). Plugin load warnings, trust warnings and refresh results are written there.

Adding a catalog fails

Message	What to do
`could not classify source`	The source string is not a form Syntic Code knows. Use `owner/repo`, a git URL, `gitlab:group/project`, a path starting with `./`, `/` or `~`, an https URL, or `npm:<package>`.
`git is required ... but was not found`	Install git, or host the catalog as a URL or npm package.
`git clone failed for ...`	Check that the repository exists and that your git credentials can reach it. Try the same `git clone` by hand. For GitHub over SSH, set `SYNTIC_PLUGIN_GIT_PROTOCOL=ssh`.
`no marketplace.json in ...`	The file must be at the root of the repository or folder. A `.syntic-plugin/marketplace.json` is read by `validate` but not by `add`.
`no marketplace listing at ... (HTTP 404)`	The URL is wrong, or the server needs a token. Add a `headersHelper` in your settings.
`unsafe marketplace name ...`	The catalog’s `name` contains characters other than letters, digits, `.`, `_` and `-`.
A message naming `blockedMarketplaces` or `strictKnownMarketplaces`	Your organization’s policy forbids this source. See Plugins for your organization.
`headersHelper` or `command` refused because it “would run a program”	That entry is in a repository’s settings. Move it to your own user settings.

Installing fails

Message	What to do
`No marketplace named <m>`	Add the catalog first, or pass `--marketplace <source>` to `syntic plugin install`, which adds it on the way.
`The marketplace at <source> is not named <m>`	The catalog you added declares a different `name`. Install with the name it declares (`syntic plugin marketplace list` shows it).
`plugin <p> not listed in marketplace <m>`	Check spelling and case, then `syntic plugin marketplace refresh <m>` in case the listing is old. `syntic plugin list --available` shows what each catalog offers.
`installing straight from a url source is not supported`	The entry has no source of its own and its catalog is a URL. The catalog owner must give the entry a git, zip or npm source.
`the source has no folder ...`	The `//folder` part of the entry does not exist at that ref.
`validating plugin ... manifest`	The fetched folder has no `.syntic-plugin/plugin.json`, `plugin.json` or `SKILL.md`, or the manifest is not valid JSON. Run `syntic plugin validate` on a local copy.
sha256 mismatch on a zip	The file changed since the pin was written. The catalog owner must update the `#sha256=` value.
npm integrity refused	The package has no `sha512` integrity, or the download did not match it.
`disabled by your organization's policy`	The plugin is set to `false` in managed `enabledPlugins`. It cannot be installed here.
`unknown --scope`	Use `user`, `project` or `local`.

A plugin whose manifest says "defaultEnabled": false installs switched off. That is intended; turn it on with syntic plugin enable <plugin>@<marketplace>.

If a plugin needs options, the install output names the required ones still unset. Set them with syntic plugin configure <plugin>@<marketplace>.

Installed, but nothing shows up

Work down this list.

Is it on? syntic plugin list shows [enabled] or [disabled].
Did the session pick it up? Run /reload-plugins. Installs and toggles made in /plugin take effect after a reload or a restart.
Is it allowed? A plugin set to false in managed enabledPlugins, or one not on the trust list when ~/.syntic/plugins/policy.json has "lockdown": true (or SYNTIC_PLUGIN_LOCKDOWN=1), does not load.
Are its dependencies loading? syntic doctor prints lines like “Plugin X is off: it needs Y, which is not installed”. Install or enable Y.
Are you in a bare or safe session? --bare skips installed plugins. --safe-mode (or SYNTIC_SAFE_MODE=1) turns all plugins off.
Is the manifest still valid? syntic plugin validate ~/.syntic/plugins/<name>.
Are you looking for the right name? Plugin commands are prefixed with the plugin name, such as /formatter:format. Type / and the plugin name to filter the menu. A user or project command with the same full name hides the plugin’s.

Specific components

Component	Check
Skills	`syntic plugin details <plugin>` lists them. When `SYNTIC_SKILLS_PLUGIN_ONLY` is set, only plugin skills are offered, so your own skills disappear instead.
Hooks	`/hooks` lists plugin hooks next to your own.
MCP servers	`/mcp` shows them as `plugin:<plugin>:<server>`. Use `--mcp-debug` to see connection errors.
Language servers	`syntic plugin details <plugin>` lists the language servers it declares. The server program must be on `PATH` or in the plugin’s `bin/` folder. See Code intelligence.
Options	A hook reads options as `SYNTIC_USER_CONFIG_<KEY>`. If a value is empty, it was never set: run `syntic plugin configure`.

A plugin behaves oddly after an update

syntic plugin update keeps the on/off state but replaces all files. Data the plugin keeps in ${SYNTIC_PLUGIN_DATA} survives; anything it wrote inside its own folder does not.
If the update failed half-way, the old copy is still in place; the error says why the new one was refused.
To go back, pin the entry to an older tag or commit in the catalog, refresh it, and update again.

Plugin files are stored in a folder named after the plugin. Installing formatter@acme and formatter@other on one machine makes the second install replace the first one’s files, even though both appear in syntic plugin list. Uninstall one of them, then update the other.

Startup is slow, or a plugin misbehaves badly

Start with --safe-mode to confirm plugins are the cause.
Turn plugins off one at a time with Space in /plugin, or all at once with syntic plugin disable-all, then turn them back on one by one.
A plugin’s MCP servers start with the session, and so do monitors declared to start at launch. syntic plugin details shows what each plugin brings.

Catalog listings look stale

syntic plugin marketplace refresh <name> fetches the listing now.
If auto-update is off for that catalog ([auto-update off] in syntic plugin marketplace list), it is refreshed only when you ask by name.
SYNTIC_PLUGIN_AUTO_UPDATE=0 or the privacy switches stop the daily background refresh.
A refresh line saying a plugin is “no longer published” means the catalog removed it. It stays installed until you remove it.

Plugins from a removed catalog

syntic plugin reconcile           # list plugins whose catalog is no longer saved
syntic plugin reconcile --prune   # remove them

Plugins installed in the managed scope are listed but never removed by --prune.

Building your own plugin

Problem	Fix
`validate` reports a path that “escapes the plugin directory”	Make component paths relative to the plugin folder, with no `..` and no leading `/` or `~`.
Changes do not appear	Load the folder with `--plugin-dir` while you work, and run `/reload-plugins` after edits.
`--plugin-dir` folder is skipped	A plugin with the same name is installed; the installed one wins. Uninstall or disable it, or rename yours while testing.
`${SYNTIC_PLUGIN_ROOT}` is not replaced	Only `${SYNTIC_PLUGIN_ROOT}`, `${SYNTIC_PLUGIN_DATA}` and `${user_config.KEY}` are recognised. Check the spelling.
Eval cases fail	See Test a plugin.

Still stuck? Run the failing command with --json and keep the output. It includes the exact error text and exit code, which makes problems much faster to diagnose.

Plugins for your organization How plugins load