Troubleshooting & FAQ

Troubleshooting & FAQ

Installation Issues

Windows: "Windows protected your PC" SmartScreen warning

SnCode is not code-signed yet. Click "More info" then "Run anyway" to proceed with installation.

macOS: "SnCode can't be opened because it is from an unidentified developer"

Right-click the app and select "Open", then click "Open" in the dialog. This only needs to be done once.

Linux: AppImage won't run

Make sure it's executable:

chmod +x SnCode-*.AppImage
./SnCode-*.AppImage

Linux: Credentials not saving

The keytar package requires libsecret. Install it:

# Debian/Ubuntu
sudo apt install libsecret-1-dev

# Fedora
sudo dnf install libsecret-devel

You may also need a keyring daemon running (e.g., GNOME Keyring).

Authentication Issues

"The model X does not exist or you do not have access to it"

This usually means:

• Your API key doesn't have access to the selected model
• Your subscription tier doesn't include the model
• The model ID is incorrect

Try switching to a different model in Settings > Providers.

OAuth: "Invalid authorization code"

The authorization code may have expired. Codes are single-use and time-limited. Try the OAuth flow again from the beginning.

OAuth: "Authorization failed or timed out" (OpenAI)

The device code flow polls for 5 minutes. If you didn't complete the browser authorization in time, try again. Make sure you enter the correct user code displayed in SnCode.

API key not working after paste

Make sure you're pasting the complete key with no extra whitespace. Keys typically start with sk- (Anthropic) or sk-proj- (OpenAI).

Agent Issues

Agent seems stuck or not responding

1. Click the Stop button to cancel the current run
2. Check your internet connection
3. Verify your API key/OAuth tokens are valid in Settings > Providers
4. Check if you've hit your API rate limit or quota

"Max tool steps reached"

The agent hit the configured limit for tool call iterations. You can:

• Increase maxToolSteps in Settings > Agent (default: 25, max: 100)
• Send a follow-up message asking the agent to continue

Agent is reading/writing files outside my project

This shouldn't happen — SnCode has path traversal protection. If you believe it occurred, please report a bug.

Commands are slow or timing out

Shell commands have a 90-second timeout. For long-running commands, consider:

• Breaking them into smaller steps
• Running them outside SnCode and pasting the output

UI Issues

Light theme looks wrong

If some elements still appear dark in light theme, it may be a rendering cache issue. Try:

1. Switch to dark theme and back
2. Close and reopen the app

If the issue persists, please report it with a screenshot.

File tree not showing files

The file tree skips certain directories by default: node_modules, .git, dist, build, and other heavy directories. Hidden files (starting with .) are also excluded.

Search not finding messages

Search only searches user and assistant message text. It does not search:

• Tool call contents
• File contents
• System messages

Performance Issues

App feels slow with long conversations

Long conversations with many messages and tool calls consume memory. Try:

• Creating a new thread for fresh topics
• Deleting old threads you no longer need

Large file operations are slow

Files over 300 KB are rejected by the read_file tool. For very large files, the agent may need to use grep or run_command to extract specific sections.

Data & Privacy

Where is my data stored?

Data	Location
App state (projects, threads, messages, settings)	{userData}/sncode-state.json
Credentials (API keys, OAuth tokens)	OS keychain
Skills	{userData}/skills/

{userData} is:

• Windows: %APPDATA%/sncode/
• macOS: ~/Library/Application Support/sncode/
• Linux: ~/.config/sncode/

How do I completely remove SnCode?

1. Uninstall the application
2. Delete the data directory (see above)
3. Credentials are automatically removed when you clear all data from Settings, or you can remove them manually from your OS keychain manager under the sncode.providers service

Does SnCode send data anywhere besides the AI providers?

No. SnCode only communicates with:

• api.anthropic.com (Anthropic API)
• api.openai.com (OpenAI API)
• claude.ai / console.anthropic.com (Anthropic OAuth)
• auth.openai.com (OpenAI OAuth)

No telemetry, analytics, or tracking of any kind.

Getting Help

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions and community help