Troubleshooting

"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):

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:

Cannot Log In to Verdent

Most common cause: Proxy configuration issue

Solution:

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

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

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 for assistance with your free trial access. The support team will review your account and help resolve the issue.

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 for assistance. The support team can review your registration and provide guidance on resolving the issue.

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 to see which models are available in your region

Performance Issues

Symptoms:

• Slow response times
• High memory usage
• Tool execution timeouts

Common causes & fixes:

Credit Limit Reached

Symptoms: Operations fail with quota error

Solutions:

1. Check balance in User Menu
2. Enable 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

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

Quick reference for common image processing errors:

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

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

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

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

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

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

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

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

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

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

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

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:

# 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)

bash Command Failures

Error: Command timeout or execution failure

Maximum Timeout: 120 seconds (2 minutes, hard limit)

Solution: Break long commands into smaller operations:

# 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

Issue: grep_file or glob not finding expected files

Check pattern syntax:

# Wrong
grep_file("*.ts")  # Missing ** for recursive

# Correct
grep_file("**/*.ts")  # Recursive search

Check exclusions:

# Ensure not accidentally excluding target files
glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])

Case sensitivity:

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

AGENTS.md 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:

# 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

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

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

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

Binary File Limitations

Issue: Cannot edit images, PDFs, compiled binaries

Workaround:

# Use bash to call external tools
bash("convert input.png -resize 50% output.png")
bash("pdftotext document.pdf output.txt")

Large File Handling

Issue: Files over 10,000 lines cause context issues

Workaround:

# 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")

Cross-Platform Command Differences

Issue: bash commands differ between Windows and Unix

Workaround:

# 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.