Troubleshooting

​

Installation & Setup Issues

• Operating System: macOS 11+, Windows 10+
• Git: Required for all projects
• Internet connection: Active connection required
• Subscription: Active Verdent subscription

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

​

Cannot Log In to Verdent

​

Authentication Failures

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

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

​

Registration Failed

​

Missing Models (Claude, GPT, Gemini)

• 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

​

Performance Issues

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

​

Credit Limit Reached

1. Check balance in User Menu
2. Switch to Claude Haiku 4.5 to conserve credits
3. Wait for monthly refresh
4. Purchase one-time top-up
5. Reduce parallel agent usage

​

Credits Depleting Quickly

• Multiple parallel agents
• Using extended context models (Claude Sonnet 4.5 1M)
• Large context in requests

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

​

Changes appearing in wrong workspace

• Working in wrong workspace
• Switched workspaces without noticing

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

1. Verdent will display the conflicting files
2. Review and resolve conflicts in the editor
3. Use Rebase to main branch again after resolving

• 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

• Verdent may prompt to run dependency installation
• Or manually run install commands in the terminal

​

Project won’t open

• Directory doesn’t exist or was moved
• Permissions issues
• Not a git repository

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

​

Recent projects missing

• Project moved or deleted
• Signed in with different account

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

• Maximum agent limit reached
• Insufficient credits
• Resource constraints

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

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

​

bash Command Failures

# Instead of one long command, break into steps
bash("step1")  # Completes in < 2min
bash("step2")  # Completes in < 2min

• Check if command exists: bash("which command-name")
• Ensure correct path or activate environment first
• Use full paths for executables

• Commands execute with user permissions
• Check file/directory permissions

​

Search Returning No Results

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

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

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

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

​

MCP Connection Failures

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

• Restart MCP server
• Verify connection string format
• Check firewall rules allowing MCP traffic
• Validate API keys or tokens

​

Subagent Not Invoking

• 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

@subagent-name perform task

​

Built-in Subagent Behavior

• Request does not match subagent’s specialization
• Subagent context full (rare)
• Main conversation context affecting routing

• Use explicit @-mention to force specific subagent
• Rephrase request to match subagent expertise
• Start fresh conversation if context is an issue

​

Large File Handling

# 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

# Use cross-platform tools when possible
bash("npm run build")  # Works everywhere

# Or conditional execution
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")