Troubleshooting
Common issues and how to resolve them.
Quick Fixes
Try these first for most issues:
1. Update to latest version:
bash
npm update -g @synoppy/cli2. Refresh authentication:
bash
synoppy logout && synoppy login3. Check status:
bash
synoppy status4. Clear session and start fresh:
text
/clearCommon Issues
Authentication failed
Symptoms:
- •"Invalid or expired token" error
- •Login redirect loop
- •401 Unauthorized responses
Solutions:
- Run `synoppy logout` then `synoppy login` to refresh credentials
- Check your internet connection
- Ensure you're using the latest version: `npm update -g synoppy`
Out of credits
Symptoms:
- •"Insufficient credits" error
- •Requests fail after working previously
Solutions:
- Check your balance: `synoppy status`
- Upgrade your plan at /pricing for more credits
- Consider using BYOK mode with your own API keys
Model not available
Symptoms:
- •"Model not found" error
- •Requests timeout on specific models
Solutions:
- Check available models: `/model`
- Use the correct shortname (e.g., `sonnet`, `haiku`, `opus`, `deepseek`, `reasoner`)
- Some models require higher plans: Opus 4.6 (Pro+), 1M context (Pro+), Gemini 3.1 Pro (Pro+)
BYOK not working
Symptoms:
- •API key errors
- •"Invalid API key" messages
- •Provider-specific errors
Solutions:
- Check BYOK status: `/byok`
- Verify your key is set: `/apikey`
- Re-add the key: `/apikey anthropic sk-ant-...`
- Test your API key directly with the provider's console
Session not saving
Symptoms:
- •Cannot continue previous session
- •Session history missing
Solutions:
- Check disk space on your system
- Verify write permissions to `~/.synoppy/`
- Try clearing cache: `rm -rf ~/.synoppy/cache`
Tool permission denied
Symptoms:
- •"Permission denied" for file operations
- •Bash commands blocked
Solutions:
- Check project permissions: `/permissions`
- Ensure the file is within the project directory
- Add the tool to `allowedTools` in synoppy.json
Slow responses
Symptoms:
- •Long wait times
- •Timeouts on large requests
Solutions:
- Use a faster model (Claude Haiku or DeepSeek Chat)
- Disable extended thinking for simple tasks: `/thinking off`
- Reduce context by starting a fresh session: `/clear`
- Check your internet connection speed
Unexpected behavior
Symptoms:
- •Wrong file edits
- •Incorrect code suggestions
- •Model seems confused
Solutions:
- Provide more context in your prompt
- Reference specific file paths
- Start a fresh session to clear context: `/clear`
- Try a more capable model (Opus 4.6 or Sonnet 4.5)
Debugging Code Issues
Use the debug command to analyze issues in your code:
bash
synoppy debug src/app.tsPass a specific error message for targeted analysis:
bash
synoppy debug src/app.ts --error "TypeError: Cannot read property"Getting More Help
Discord Community
Join our Discord for real-time help from the community and team.
Email Support
Contact us at support@synoppy.com for account or billing issues.
Documentation
Browse our documentation for detailed guides and references.