Troubleshooting

This document provides solutions to common problems.

---

Installation Issues

Issue: Installation script download failed

Symptoms: Network error when running installation command

Solutions:

1. Check network connection
2. Try using a proxy
3. Manual download: visit https://carrycode.ai/releases

Issue: Permission denied

Symptoms: Permission denied error

Solutions:

# Linux/macOS
sudo sh install.sh

# Windows
Run PowerShell as administrator

Issue: Cannot find carry command

Symptoms: Installation successful but cannot run

Solutions:

1. Confirm installation path is in PATH
2. Reload terminal config: source ~/.bashrc or source ~/.zshrc
3. Check installation location: ls /usr/local/bin/carry

---

Connection Issues

Issue: Cannot connect to AI service

Symptoms: Network error or timeout

Solutions:

1. Check network connection
2. If using proxy, configure proxy environment variables
3. Try changing AI provider
4. Check if API Key is correct

Issue: Invalid API Key

Symptoms: API Key error

Solutions:

1. Confirm API Key is copied completely
2. Check Key status in provider dashboard
3. Regenerate API Key

---

Interface Issues

Issue: Interface display garbled

Symptoms: Characters displayed in wrong positions

Solutions:

1. Switch theme: /theme
2. Change terminal application
3. Check terminal encoding settings (should be UTF-8)

Issue: Chinese characters display incorrectly

Symptoms: Chinese characters display abnormally

Solutions:

1. Confirm terminal supports UTF-8
2. Set environment variable: export LANG=en_US.UTF-8

Issue: Theme not taking effect

Symptoms: No change after switching theme

Solutions:

1. Restart Carry Code
2. Check config file format

---

Function Issues

Issue: AI cannot read files

Symptoms: File doesn’t exist or permission denied

Solutions:

1. Confirm file path is correct
2. Check file permissions
3. Confirm file is within workspace

Issue: AI cannot execute commands

Symptoms: Command execution fails

Solutions:

1. Check approval mode settings
2. Confirm command syntax is correct
3. Check command permissions

Issue: MCP server connection failed

Symptoms: Cannot connect to MCP server

Solutions:

1. Confirm server is running
2. Check server address
3. Test network connection
4. Check server logs

---

Performance Issues

Issue: Slow response

Symptoms: Long wait time for AI responses

Solutions:

1. Choose provider with better network latency
2. Use lighter models
3. Check local network speed

Issue: High memory usage

Symptoms: System memory usage too high

Solutions:

1. Compress session context: /compact
2. Create new session
3. Close unnecessary applications

Issue: Token limit exceeded

Symptoms: Token limit exceeded error

Solutions:

1. Use /compact to compress context
2. Create new session
3. Use more concise prompts

---

Configuration Issues

Issue: Config file format error

Symptoms: Config not taking effect

Solutions:

1. Check JSON format correctness
2. Use JSON validation tool
3. Delete config file and reconfigure

Issue: AGENTS.md not taking effect

Symptoms: Rules not applied

Solutions:

1. Confirm file is in project root
2. Check file format
3. Restart Carry Code

---

Session Issues

Issue: Session not saved

Symptoms: Conversation lost after restart

Solutions:

1. Check session directory permissions
2. Confirm sufficient disk space
3. Check log files

Issue: Cannot switch sessions

Symptoms: Session switch failed

Solutions:

1. Confirm session name is correct
2. Check if session file exists
3. Restart Carry Code

---

Update Issues

Issue: Update failed

Symptoms: /update command fails

Solutions:

1. Check network connection
2. Manually download new version
3. Reinstall

Issue: Function abnormal after update

Symptoms: Problems with new version

Solutions:

1. Rollback to old version
2. Delete config and reconfigure
3. Report issue to GitHub

---

Getting Help

If none of the above solutions work:

1. View documentation: https://docs.carrycode.ai
2. Community support: https://carrycode.ai
3. Report issues: https://github.com/carrycode/carrycode/issues