Documentation Index Fetch the complete documentation index at: https://docs.verdent.ai/llms.txt
Use this file to discover all available pages before exploring further.
What You’ll 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 for specific issues not covered here. Quick Diagnostics ”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 and Retry
Wait 30-60 seconds and try your request again. Most service issues resolve quickly.
Roll Back Message
If the error persists, roll back the most recent message using the undo button in the chat interface.
Start New Task
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
Installation & Setup Issues System Requirements:
Operating System: macOS 11+, Windows 10+Git: Required for all projectsInternet connection: Active connection requiredSubscription: Active Verdent subscription Basic diagnostic checklist:
Verify installation: Application launches without errorsCheck internet connection: Verdent requires an active connectionVerify subscription: Ensure Verdent subscription is activeCheck Git: Run git --version to verify Git is installed Clean Reinstall Procedure:
Uninstall Verdent
Remove the application using your OS standard uninstall process
Remove Configuration
Delete ~/.verdent/ directory to clear all settings
Reinstall
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 Most common cause: Proxy configuration issueSolution:
Open Settings
Press Cmd+, (macOS) or Ctrl+, (Windows)
Find Proxy Setting
Navigate to network or proxy settings
Toggle Proxy Status
Toggle the proxy setting on/off (opposite of current state)
Retry Login
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 Symptoms: Sign-in doesn’t work, or session expires frequentlySolutions:
Sign out and sign in again
Clear authentication cache: Settings → Account → Sign Out
Check that browser can complete OAuth flow
Verify account status at verdent.ai/account
Requests Fail Behind Corporate Firewall Symptoms: Works on home network but not at workSolutions:
Contact IT to whitelist Verdent API endpoints
Configure proxy settings if required
Check if SSL inspection is blocking connections
Try using a VPN if permitted
Free Trial Credits Not Received Error: Free trial credits were not received or free trial access deniedReason: Terms of service violation detected during registrationResolution: 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 restrictedReason: The registration violated Verdent’s terms of service, resulting in access restrictionResolution: 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 selectionReason: Location-based restrictions from model providersExplanation: 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 regionRegional restrictions are set by the AI model providers (Anthropic, OpenAI, Google), not by Verdent. Verdent cannot override these restrictions.
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 Symptoms: Operations fail with quota errorSolutions:
Check balance in User Menu
Enable Eco Mode if your subscription is active
Wait for the next billing-cycle refresh
Purchase a one-time top-up
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:
Use Claude Haiku 4.5 for routine tasks
Limit parallel agents (2-3 recommended)
Start fresh tasks to reduce context size
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 Workspace Issues
Workspace Isolation
Project Issues
Parallel Agents
Cannot create new workspace Causes:
Uncommitted changes in current workspace
Insufficient disk space
Solutions:
Commit or discard changes in Source Control panel before creating new workspace
Delete unused workspaces to free disk space
Restart Verdent and try again
Workspace appears stuck or unresponsive Solutions:
Switch to a different workspace using All Workspaces
Delete the stuck workspace from the Workspace Bar
Restart Verdent
Workspace not appearing in list Solutions:
Click All Workspaces to refresh the workspace list
Check if the workspace was deleted
Restart Verdent to reload workspace state
Changes appearing in wrong workspace Causes:
Working in wrong workspace
Switched workspaces without noticing
Solutions:
Check current workspace name in the Workspace Bar
Use All Workspaces to switch to the correct workspace
Review changes to confirm which workspace has your work
Rebase conflicts when combining workspaces When rebasing to master shows conflicts:
Verdent will display the conflicting files
Review and resolve conflicts in the editor
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 dependenciesSolution: 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:
Use Current Project → New Project to browse and select the directory
Check that the project directory exists and is accessible
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 repositorySolution: 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:
Use Current Project → New Project to manually browse
Check if project directory still exists
Verify signed in with correct account in User Menu
Parallel agent not starting Causes:
Maximum agent limit reached
Insufficient credits
Resource constraints
Solutions:
Check current agent count in sidebar
Close unused agents to free slots
Verify credit balance
Restart application if agents appear stuck
Agent coordination issues Symptoms: Agents working on same files, conflictsPrevention:
Use Plan Mode to coordinate work assignments
Assign different files/directories to each agent
Review agent tasks before starting parallel work
Use workspace isolation for complex parallel tasks
file_edit Failures
bash Failures
Search Issues
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 )
Always read the file immediately before editing to ensure you have the current state.
bash Command Failures Error: Command timeout or execution failureMaximum 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 filesCheck 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 )
Configuration Issues AGENTS.md Rules
MCP Connection
Subagent Issues
Built-in Subagents
AGENTS.md Not Applied Problem: Project rules not affecting Verdent behaviorDiagnostic:
Location: File must be in project root directorySyntax: Valid Markdown (check for syntax errors)Specificity: Rules must be directive: “Always use X” not “Try to use X”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 serverDiagnostic steps:
Check mcp.json: Valid JSON syntax in ~/.verdent/mcp.jsonServer running: Ensure MCP server process is activeNetwork: Verify connectivity to server endpointAuthentication: Confirm credentials are correctLogs: 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 automaticallyChecklist: Test manually: @subagent-name perform task
Use explicit @-mention to verify the subagent works before troubleshooting automatic invocation.
Built-in Subagent Behavior Issue: @verifier not behaving as expectedCommon 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 Binary Files
Large Files
Platform Differences
Binary File Limitations Issue: Cannot edit images, PDFs, compiled binariesWorkaround: # 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 Issue: Files over 10,000 lines cause context issuesWorkaround: # 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.
Issue: bash commands differ between Windows and UnixWorkaround: # 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 Support Channels For specific issues not covered here: When reporting issues, include:
Verdent version (Help → About)
Operating system and version
Error messages (exact text)
Steps to reproduce
Workspace state (if relevant)
Expected vs actual behavior
See Also
Error Recovery Detailed recovery procedures
FAQs Frequently asked questions
