# Troubleshooting (/docs/verdent/help-support/common-issues)
> Common issues, diagnostics, and solutions
## What You'll Learn [#what-youll-learn]
Common troubleshooting procedures, diagnostic steps, and known issue workarounds for Verdent.
Detailed troubleshooting for top user-reported issues is being compiled from support data. This page provides general diagnostic procedures. Contact [support@verdent.ai](mailto:support@verdent.ai) for specific issues not covered here.
***
## Quick Diagnostics [#quick-diagnostics]
### "Service is experiencing high traffic. Please try again later!" [#service-is-experiencing-high-traffic-please-try-again-later]
**This is the #1 most common error** users encounter. It indicates the Verdent service is temporarily overloaded.
**When it happens:**
* During peak usage times
* When backend services are under heavy load
* Temporary service degradation
**Recovery steps (in order):**
Wait 30-60 seconds and try your request again. Most service issues resolve quickly.
If the error persists, roll back the most recent message using the undo button in the chat interface.
If errors continue, start a fresh task:
* Click **New Task** to create a new conversation
* The new task starts with fresh context
* Resubmit your request in the new task
* Delete the old task if no longer needed
If the issue persists for more than 5-10 minutes across multiple tasks, check the [Verdent status page](https://verdent.ai/status) or contact [support@verdent.ai](mailto:support@verdent.ai).
### Installation & Setup Issues [#installation--setup-issues]
**System Requirements:**
* **Operating System:** macOS 11+, Windows 10+
* **Git:** Required for all projects
* **Internet connection:** Active connection required
* **Subscription:** Active Verdent subscription
**Basic diagnostic checklist:**
1. **Verify installation:** Application launches without errors
2. **Check internet connection:** Verdent requires an active connection
3. **Verify subscription:** Ensure Verdent subscription is active
4. **Check Git:** Run `git --version` to verify Git is installed
**Clean Reinstall Procedure:**
Remove the application using your OS standard uninstall process
Delete `~/.verdent/` directory to clear all settings
Download fresh installer from verdent.ai and install
Most installation issues resolve with a clean reinstall. If issues persist, check logs and contact support with log details.
### Cannot Log In to Verdent [#cannot-log-in-to-verdent]
**Most common cause:** Proxy configuration issue
**Solution:**
Press `Cmd+,` (macOS) or `Ctrl+,` (Windows)
Navigate to network or proxy settings
Toggle the proxy setting on/off (opposite of current state)
Try logging in to Verdent again
If you're behind a corporate firewall, you may need to enable the proxy setting. If you're on a home network, try disabling it.
***
### Authentication Failures [#authentication-failures]
**Symptoms:** Sign-in doesn't work, or session expires frequently
**Solutions:**
1. Sign out and sign in again
2. Clear authentication cache: Settings → Account → Sign Out
3. Check that browser can complete OAuth flow
4. Verify account status at [verdent.ai/account](https://verdent.ai/account)
***
### Requests Fail Behind Corporate Firewall [#requests-fail-behind-corporate-firewall]
**Symptoms:** Works on home network but not at work
**Solutions:**
1. Contact IT to whitelist Verdent API endpoints
2. Configure proxy settings if required
3. Check if SSL inspection is blocking connections
4. Try using a VPN if permitted
***
### Free Trial Credits Not Received [#free-trial-credits-not-received]
**Error:** Free trial credits were not received or free trial access denied
**Reason:** Terms of service violation detected during registration
**Resolution:** Contact [support@verdent.ai](mailto:support@verdent.ai) for assistance with your free trial access. The support team will review your account and help resolve the issue.
***
### Registration Failed [#registration-failed]
**Error:** Account registration was rejected or restricted
**Reason:** The registration violated Verdent's terms of service, resulting in access restriction
**Resolution:** Contact [support@verdent.ai](mailto:support@verdent.ai) for assistance. The support team can review your registration and provide guidance on resolving the issue.
***
### Missing Models (Claude, GPT, Gemini) [#missing-models-claude-gpt-gemini]
**Issue:** Cannot find Claude, GPT, or Gemini models in model selection
**Reason:** Location-based restrictions from model providers
**Explanation:** Some AI model providers have regional restrictions that prevent certain models from being available in specific geographic locations. When this happens:
* Restricted models will not appear in your model selection menu
* You can still use all other available models without interruption
* No impact on your subscription or credits
**Check Available Models:** Visit [https://www.verdent.ai/regions](https://www.verdent.ai/regions) to see which models are available in your region
Regional restrictions are set by the AI model providers (Anthropic, OpenAI, Google), not by Verdent. Verdent cannot override these restrictions.
### Performance Issues [#performance-issues]
**Symptoms:**
* Slow response times
* High memory usage
* Tool execution timeouts
**Common causes & fixes:**
| Issue | Cause | Solution |
| -------------- | ------------------------ | ------------------------------- |
| Slow responses | Large context | Start new task to clear context |
| High memory | Multiple parallel agents | Reduce to 2-3 concurrent agents |
| Timeouts | Network latency | Check connection, retry request |
| System slow | Too many workspaces | Close unused workspaces |
Use Claude Haiku 4.5 for routine tasks to reduce resource consumption.
### Credit Limit Reached [#credit-limit-reached]
**Symptoms:** Operations fail with quota error
**Solutions:**
1. Check balance in User Menu
2. Enable [Eco Mode](/docs/account-billing/eco-mode) if your subscription is active
3. Wait for the next billing-cycle refresh
4. Purchase a one-time top-up
5. Upgrade your plan if you regularly hit this limit
***
### Credits Depleting Quickly [#credits-depleting-quickly]
**Causes:**
* Multiple parallel agents
* Using extended context models (Claude Sonnet 4.5 1M)
* Large context in requests
**Solutions:**
1. Use Claude Haiku 4.5 for routine tasks
2. Limit parallel agents (2-3 recommended)
3. Start fresh tasks to reduce context size
### Image-Related Error Messages [#image-related-error-messages]
**Quick reference for common image processing errors:**
| Error Message | Cause | Solution |
| ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| **Unsupported Image Type** | Only JPEG, PNG, GIF, or WebP images are supported | Roll back and change the image type to a supported format |
| **Image Dimensions Too Large** | Image width or height cannot exceed 8000 pixels | Roll back and adjust image dimensions to 8000×8000 or smaller |
| **Input Too Long** | The input exceeds the model's maximum allowed length | Simplify your input or reduce image size |
| **File Too Large** | Image size cannot exceed 5 MB | Roll back and send a compressed image (max 5 MB) |
| **Unreadable Image** | Could not process the image, file may be corrupted or unsupported format | Roll back and replace the image with a valid file |
***
## Desktop-Specific Issues [#desktop-specific-issues]
### Cannot create new workspace [#cannot-create-new-workspace]
**Causes:**
* Uncommitted changes in current workspace
* Insufficient disk space
**Solutions:**
1. Commit or discard changes in Source Control panel before creating new workspace
2. Delete unused workspaces to free disk space
3. Restart Verdent and try again
***
### Workspace appears stuck or unresponsive [#workspace-appears-stuck-or-unresponsive]
**Solutions:**
1. Switch to a different workspace using **All Workspaces**
2. Delete the stuck workspace from the Workspace Bar
3. Restart Verdent
***
### Workspace not appearing in list [#workspace-not-appearing-in-list]
**Solutions:**
1. Click **All Workspaces** to refresh the workspace list
2. Check if the workspace was deleted
3. Restart Verdent to reload workspace state
### Changes appearing in wrong workspace [#changes-appearing-in-wrong-workspace]
**Causes:**
* Working in wrong workspace
* Switched workspaces without noticing
**Solutions:**
1. Check current workspace name in the Workspace Bar
2. Use **All Workspaces** to switch to the correct workspace
3. Review changes to confirm which workspace has your work
***
### Rebase conflicts when combining workspaces [#rebase-conflicts-when-combining-workspaces]
**When rebasing to master shows conflicts:**
1. Verdent will display the conflicting files
2. Review and resolve conflicts in the editor
3. Use **Rebase to main branch** again after resolving
**Prevention:**
* Assign different files/directories to each parallel agent
* Use **Sync with main branch** regularly to reduce drift
* Use Plan Mode to review changes before rebase
***
### Dependencies not installed in new workspace [#dependencies-not-installed-in-new-workspace]
**Cause:** Each workspace has its own dependencies
**Solution:** Install dependencies when creating a new workspace:
* Verdent may prompt to run dependency installation
* Or manually run install commands in the terminal
### Project won't open [#project-wont-open]
**Causes:**
* Directory doesn't exist or was moved
* Permissions issues
* Not a git repository
**Solutions:**
1. Use **Current Project → New Project** to browse and select the directory
2. Check that the project directory exists and is accessible
3. For non-git projects, Verdent will initialize git automatically
***
### Nested Git repository issues [#nested-git-repository-issues]
**Cause:** The selected directory's parent folder or subfolder is already a Git repository
**Solution:** Select a single Git repository as the project root. Support for nested Git repositories is currently limited.
***
### Recent projects missing [#recent-projects-missing]
**Causes:**
* Project moved or deleted
* Signed in with different account
**Solutions:**
1. Use **Current Project → New Project** to manually browse
2. Check if project directory still exists
3. Verify signed in with correct account in User Menu
### Parallel agent not starting [#parallel-agent-not-starting]
**Causes:**
* Maximum agent limit reached
* Insufficient credits
* Resource constraints
**Solutions:**
1. Check current agent count in sidebar
2. Close unused agents to free slots
3. Verify credit balance
4. Restart application if agents appear stuck
***
### Agent coordination issues [#agent-coordination-issues]
**Symptoms:** Agents working on same files, conflicts
**Prevention:**
1. Use Plan Mode to coordinate work assignments
2. Assign different files/directories to each agent
3. Review agent tasks before starting parallel work
4. Use workspace isolation for complex parallel tasks
***
## Tool-Specific Issues [#tool-specific-issues]
### file\_edit Failures [#file_edit-failures]
**Error:** "Failed to find exact match"
**Causes:**
* Text changed since last file\_read
* Whitespace differences (tabs vs spaces)
* String not unique in file
**Solutions:**
```bash
# 1. Read file again to get current state
file_read("file.js")
# 2. Use larger context string for uniqueness
file_edit("file.js",
old_string="function foo() {\n return 42;\n}",
new_string="...")
# 3. For multiple identical strings, use replace_all
file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
```
Always read the file immediately before editing to ensure you have the current state.
### bash Command Failures [#bash-command-failures]
**Error:** Command timeout or execution failure
**Maximum Timeout:** 120 seconds (2 minutes, hard limit)
**Solution:** Break long commands into smaller operations:
```bash
# Instead of one long command, break into steps
bash("step1") # Completes in < 2min
bash("step2") # Completes in < 2min
```
**Command not found:**
* Check if command exists: `bash("which command-name")`
* Ensure correct path or activate environment first
* Use full paths for executables
**Permission errors:**
* Commands execute with user permissions
* Check file/directory permissions
### Search Returning No Results [#search-returning-no-results]
**Issue:** grep\_file or glob not finding expected files
**Check pattern syntax:**
```bash
# Wrong
grep_file("*.ts") # Missing ** for recursive
# Correct
grep_file("**/*.ts") # Recursive search
```
**Check exclusions:**
```bash
# Ensure not accidentally excluding target files
glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
```
**Case sensitivity:**
```bash
# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)
```
***
## Configuration Issues [#configuration-issues]
### AGENTS.md Not Applied [#agentsmd-not-applied]
**Problem:** Project rules not affecting Verdent behavior
**Diagnostic:**
1. **Location:** File must be in project root directory
2. **Syntax:** Valid Markdown (check for syntax errors)
3. **Specificity:** Rules must be directive: "Always use X" not "Try to use X"
4. **Testing:** Start new conversation to test fresh application
**Precedence check:**
```markdown
# In AGENTS.md (highest priority)
- Use 4-space indentation
# In VERDENT.md (lower priority)
- Use 2-space indentation
# Result: 4-space indentation (AGENTS.md wins)
```
### MCP Connection Failures [#mcp-connection-failures]
**Error:** Cannot connect to MCP server
**Diagnostic steps:**
1. **Check mcp.json:** Valid JSON syntax in `~/.verdent/mcp.json`
2. **Server running:** Ensure MCP server process is active
3. **Network:** Verify connectivity to server endpoint
4. **Authentication:** Confirm credentials are correct
5. **Logs:** Check MCP server logs for error details
**Common fixes:**
* Restart MCP server
* Verify connection string format
* Check firewall rules allowing MCP traffic
* Validate API keys or tokens
### Subagent Not Invoking [#subagent-not-invoking]
**Problem:** Custom subagent doesn't activate automatically
**Checklist:**
* [ ] File location: `~/.verdent/subagents/[name].md`
* [ ] Valid YAML frontmatter with `name` and `description`
* [ ] Invocation policy matches usage (strict requires @-mention)
* [ ] "When to use" guidelines match request pattern
* [ ] No syntax errors in markdown file
**Test manually:**
```
@subagent-name perform task
```
Use explicit @-mention to verify the subagent works before troubleshooting automatic invocation.
### Built-in Subagent Behavior [#built-in-subagent-behavior]
**Issue:** @verifier not behaving as expected
**Common causes:**
* Request does not match subagent's specialization
* Subagent context full (rare)
* Main conversation context affecting routing
**Solution:**
* Use explicit @-mention to force specific subagent
* Rephrase request to match subagent expertise
* Start fresh conversation if context is an issue
***
## Known Issues & Workarounds [#known-issues--workarounds]
### Binary File Limitations [#binary-file-limitations]
**Issue:** Cannot edit images, PDFs, compiled binaries
**Workaround:**
```bash
# Use bash to call external tools
bash("convert input.png -resize 50% output.png")
bash("pdftotext document.pdf output.txt")
```
Binary file modifications require external tools invoked via bash commands.
### Large File Handling [#large-file-handling]
**Issue:** Files over 10,000 lines cause context issues
**Workaround:**
```bash
# Always use line ranges for large files
file_read("large.log", start_line=1000, max_lines=100)
# Search first to find relevant sections
grep_content("ERROR", glob="large.log")
```
Search with grep\_content first to locate relevant line numbers, then read only those specific ranges.
### Cross-Platform Command Differences [#cross-platform-command-differences]
**Issue:** bash commands differ between Windows and Unix
**Workaround:**
```bash
# Use cross-platform tools when possible
bash("npm run build") # Works everywhere
# Or conditional execution
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
```
**Best practice:** Use npm scripts for cross-platform compatibility.
***
## Getting Additional Help [#getting-additional-help]
### Support Channels [#support-channels]
**For specific issues not covered here:**
* **Email:** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord:** [Join the Verdent community](https://discord.com/invite/NGjXEZcbJq) for real-time support
* **In-app:** Help → Report Issue
**When reporting issues, include:**
1. Verdent version (Help → About)
2. Operating system and version
3. Error messages (exact text)
4. Steps to reproduce
5. Workspace state (if relevant)
6. Expected vs actual behavior
***
## See Also [#see-also]
Detailed recovery procedures
Frequently asked questions