Troubleshoot Syntic Code
Start with three quick checks, then find your symptom below. Most problems are a program that is not on your PATH, a sign-in that did not finish, a plan or billing block, or a company network.
Three quick checks
syntic --version # is it installed, and which version?
syntic auth status # are you signed in? (exit code 0 = yes)
syntic doctor # full health checksyntic doctor reports where files are kept, invalid settings, the credential in use and when it expires, any organization policy, damaged saved sessions and the privacy level.
Installing and starting
| Symptom | Fix |
|---|---|
| An install command does not work | Syntic Code won’t install |
syntic: command not found | Syntic Code: command not found |
| ”Syntic Code is already running here” | Open a new terminal tab. One terminal runs one session. |
| A session says your version is no longer supported | Update Syntic Code |
Signing in and plans
| Symptom | Fix |
|---|---|
| The browser opens, but the terminal keeps waiting | Syntic Code sign-in loop |
”Not signed in. Run syntic login …” | Sign in to Syntic Code |
| ”Your session has expired …” | Run syntic login again. |
| ”Your account is a free one …” or “Your plan isn’t active …” | Use Syntic Code with your individual plan |
| A limit message with a reset time | Usage analytics and limits |
| The wrong account or plan shows | Sign out or switch accounts |
Connection
| Symptom | Fix |
|---|---|
| ”Can’t reach the Syntic server — check your internet” with a countdown | Syntic Code behind a proxy or firewall |
| ”Rate limited — retrying in …” | Nothing to do; it retries by itself. |
| ”The service stayed busy … through several retries” | Wait a minute, or switch model. See Model configuration. |
The agent and your files
| Symptom | What it means |
|---|---|
| ”Refusing to edit …” | The agent had not read the file in this session. It reads it and tries again. |
| An edit refused because the file changed | Someone edited the file after the agent read it. Your change is protected; the agent re-reads it. |
| A write outside the project is refused | Add the folder with /add-dir <path> if the agent should work there. |
| ”Permission denied: requires interactive approval…” | A -p run needed approval. Allow the tools it needs up front. |
| A command was refused as critical | It could have done serious damage, so it is always blocked. |
Rule out your own setup
Start syntic --safe-mode to switch off memory files, plugins, skills, hooks and tool servers for one run. If the problem goes away, turn things back on one at a time.
Send us a report
⚠️
Read any log or report before you send it, and remove anything private. Never send API keys or tokens.
- Run
syntic --debug --debug-file ~/syntic-debug.logand reproduce the problem. - Type
/feedback <what happened>in the session. It saves a report on your computer and shows where; nothing is uploaded. - Contact support with both files, the output of
syntic --versionand your operating system.
Learn more
Was this page helpful?