Troubleshooting

Common errors and how to fix them. Run syntic doctor first — it diagnoses 90% of issues automatically.

Installation

`syntic: command not found`

The binary is installed but not on PATH.

echo 'export PATH="$HOME/.syntic/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Windows, restart your terminal — the installer adds to PATH but existing sessions don’t pick it up.

`bad CPU type in executable` (macOS)

You downloaded the Intel build on Apple Silicon (or vice versa). Re-install:

syntic uninstall
curl -fsSL https://syntic.ai/install.sh | sh

The installer auto-detects architecture.

Authentication

`Error: not authenticated`

syntic login

If the browser flow fails, use a device code:

syntic login --device

`Error: token expired`

syntic logout && syntic login

Check that your IdP returns the email claim. Run syntic login --debug to see the SAML/OIDC response. Contact your IT admin if the claim is missing.

Models

`Error: model not available in your plan`

syntic config get model.default
syntic config set model.default kimi-k2-6

Or upgrade your plan at syntic.ai/pricing.

`Error: provider credentials missing`

Set the API key for the provider:

export ANTHROPIC_API_KEY=sk-ant-...
# or
syntic config set providers.anthropic.apiKey sk-ant-...

Rate limit errors

Configure a fallback in settings.json:

{ "model": { "default": "kimi-k2-6", "fallback": "claude-sonnet-4-6" } }

Network

Behind a corporate proxy

export HTTPS_PROXY=http://proxy.corp.example:8080
export HTTP_PROXY=http://proxy.corp.example:8080
syntic doctor   # confirms proxy is honored

TLS handshake fails

If your network does TLS inspection, add the corporate CA:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-root.pem

Tool Errors

`Permission denied` on every Bash call

Permission mode is approve and you’re hitting prompts. Either:

Add a pattern to allow: "Bash(npm test:*)" in settings
Switch mode: syntic --permission-mode accept-edits

Edit tool: “File has not been read yet”

The agent must Read a file before Editing it in the same session. This is a safety feature — usually means the agent skipped a step. Ask it to re-read the file.

Hook is silently ignored

Run with SYNTIC_LOG_LEVEL=debug syntic and watch for hook.skipped events. Common causes:

Matcher doesn’t match (case-sensitive)
Hook script is not executable (chmod +x)
Hook returned non-zero exit but no JSON

Performance

Cold start is slow

Should be sub-100ms. If it’s seconds:

Anti-virus scanning the binary on every launch (Windows Defender, macOS XProtect on first run)
Slow PATH lookup (too many entries)
~/.syntic/ on a network filesystem

Large repo indexing takes forever

syntic config set indexing.exclude '["node_modules/**", ".git/**", "dist/**", "build/**"]'
syntic index reset

Sessions

Resume fails with “session not found”

Sessions older than the retention window are pruned. Default is 30 days; change with:

{ "sessions": { "retentionDays": 90 } }

`compact` triggers too often

Increase the threshold:

{ "context": { "compactAtPercent": 85 } }

Logs

syntic logs --tail 100
syntic logs --session <id>

Logs live at ~/.syntic/logs/ and rotate at 50 MB.

Still Stuck?

IDE Integrations Changelog