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:

• VS Code version: 1.90.0 or later (required)
• Internet connection: Active connection required
• Subscription: Active Verdent subscription

Basic diagnostic checklist:

1. Verify VS Code version: Help → About (must be 1.90.0+)
2. Check internet connection: Verdent requires an active connection
3. Verify subscription: Ensure Verdent subscription is active
4. Restart VS Code: After installation or configuration changes
5. Check extension status: View → Extensions → Verdent (should show "Enabled")

Clean Reinstall Procedure:

Check Logs:

• Open Output panel: View → Output
• Select "Verdent" from the dropdown
• Look for error messages or stack traces

Cannot Log In to Verdent for VS Code

Most common cause: Proxy configuration issue

Solution:

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
• Context window full errors
• Tool execution timeouts

Common causes & fixes:

Image-Related Error Messages

Quick reference for common image processing errors:

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
• Use sudo only if necessary and in Manual Accept Mode
• 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)

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: @Explorer, @Verifier, or @Code-reviewer 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

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

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.