Troubleshooting

Something not working? Start here.

First, three quick checks

syntic --version        # is the binary on your PATH, and which version?
syntic auth status      # are you signed in?
syntic doctor           # folders, settings, model, credentials, install, policy

Inside a session, /doctor (also /checkup) shows the same health check plus checks of your MCP servers and memory files, and /status shows your account, plan, model and mode. Both syntic doctor and /doctor also list this project’s damaged saved sessions, each with what to do.

Find the problem by symptom

Symptom	Go to
`syntic: command not found`, installer errors, update errors	Install & sign-in
The browser sign-in does not finish, “Not signed in”, “session has expired”	Install & sign-in
A red error in the conversation, a refused tool call, an exit code you do not expect	Error messages
Slow start, slow replies, high memory, flicker, odd keys	Speed & stability
Plan refused, usage limits, costs that look wrong	Usage & billing

Is it my configuration?

Start a clean session to rule out your own setup:

Start with	Turns off
`syntic --safe-mode`	Memory files, plugins, skills, hooks and every MCP server.
`syntic --bare`	Settings hooks, plugins, skill discovery and auto memory.
`syntic --setting-sources user`	Project and local settings files.

If the problem goes away, turn things back on one at a time. /hooks, /mcp, /plugin and /skills let you switch individual pieces off for the session.

Settings problems:

syntic doctor reports settings files that are not valid JSON and keys with the wrong type (those keys are ignored; the rest of the file still applies).
syntic config list --project (or --local) shows exactly what a file contains.
A project’s settings, hooks and MCP servers are ignored until you trust the folder. If they seem to do nothing, check that the folder is listed in ~/.syntic/trusted_folders.

Turn on debug logs

How	Logs
`syntic --debug`	Detailed logs to standard error.
`syntic --debug api,hooks`	Only those areas.
`syntic --debug --debug-file /tmp/syntic.log`	Also to a file.
`syntic --mcp-debug`	MCP connections only (interactive sessions write to `~/.syntic/logs/syntic.log`).
`/debug <what is wrong>`	Turns on debug logging in a running session and notes the problem.

A step-by-step checklist for settings, memory, MCP servers and hooks that do not seem to apply is on Debug your configuration.

Report a problem

/feedback <what happened> saves a report with your session details on your computer and shows where. Add --with-transcript to include the conversation with likely secrets masked. Nothing is uploaded automatically.

If you need help from the Syntic team, contact support at support.syntic.ai and attach the report file /feedback saved, or describe what happened and include the output of syntic doctor.

Code review Install and sign-in