Troubleshooting & FAQ

Get help with common issues and find answers to frequently asked questions

🚀 Installation Problems

Extension Won't Install in VS Code

Problem:

VS Code shows "Extension installation failed" or the extension doesn't appear in the extensions list.

Solutions:

  1. Check VS Code Version: Ensure you're running VS Code 1.84.0 or later
  2. Clear Extension Cache: Restart VS Code with extensions disabled, then re-enable
  3. Manual Installation: Download the VSIX file and install manually: 
    code --install-extension AgentOne-7.1.0.vsix
  4. Check Permissions: Ensure VS Code has proper file system permissions

Node.js Dependency Issues

Problem:

Error messages about missing Node.js modules or version incompatibility.

Solutions:

  1. Update Node.js: Install Node.js v14 or later from nodejs.org
  2. Clear npm Cache: 
    npm cache clean --force
  3. Reinstall Dependencies: Navigate to extension folder and run: 
    npm install --production

🔌 API Connection Issues

Authentication Failed

Problem:

Getting "Invalid API key" or "Authentication failed" errors.

Solutions:

  1. Verify API Key: Check that your API key is correctly copied (no extra spaces)
  2. Check Key Permissions: Ensure your API key has the necessary permissions
  3. Test with curl: 
    # For Anthropic
curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages

# For OpenAI  
curl -H "Authorization: Bearer YOUR_KEY" https://api.openai.com/v1/models
  4. Regenerate Key: Create a new API key from your provider's dashboard

Network Connectivity Issues

Problem:

Timeout errors or "Network request failed" messages.

Solutions:

  1. Check Internet Connection: Verify you can access other websites
  2. Corporate Firewall: Ask IT to whitelist:
    • api.anthropic.com
    • api.openai.com
    • generativelanguage.googleapis.com
  3. Proxy Settings: Configure proxy in VS Code settings if needed
  4. VPN Issues: Try disabling VPN temporarily to test

⚡ Performance Issues

Slow Response Times

Problem:

AgentOne takes a long time to respond or seems to hang.

Solutions:

  1. Adjust Maestro Settings: Set analysis depth to "shallow" for faster responses
  2. Reduce Context Size: Work with smaller file selections
  3. Check System Resources: Ensure adequate RAM and CPU availability
  4. Switch Models: Try a faster model like GPT-3.5-turbo for quick tasks
  5. Close Other Extensions: Disable unnecessary VS Code extensions

High Memory Usage

Problem:

VS Code or AgentOne consuming excessive memory.

Solutions:

  1. Restart VS Code: Reload the window to clear memory leaks
  2. Disable Checkpoints: Set enableCheckpoints: false for large projects
  3. Limit File Analysis: Use .gitignore patterns to exclude large directories
  4. Clear Cache: Delete VS Code workspace cache files

🌐 Browser Automation Issues

Chrome Won't Launch

Problem:

Browser automation fails with "Chrome not found" or launch errors.

Solutions:

  1. Install Chrome: Download and install Google Chrome
  2. Set Custom Path: Configure chromeExecutablePath in settings: 
    // Windows
"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"

// macOS  
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

// Linux
"/usr/bin/google-chrome"
  3. Permissions: Ensure Chrome executable has proper permissions
  4. Disable Security Software: Temporarily disable antivirus if blocking

Browser Sessions Hang

Problem:

Browser automation starts but gets stuck or doesn't complete tasks.

Solutions:

  1. Check Page Loading: Ensure target websites are accessible
  2. Increase Timeouts: Some sites need more time to load
  3. Disable Browser Extensions: Launch Chrome in clean mode
  4. Clear Browser Data: Remove cookies and cache that might interfere

❓ General Questions

What makes AgentOne different from other AI coding assistants?

AgentOne features a unique Maestro architecture that provides multi-stage reasoning, deep context awareness, and human-in-the-loop safety controls. Unlike simple code completion tools, AgentOne can handle complex, multi-file tasks with intelligent planning and execution.

Does AgentOne require an internet connection?

Yes, AgentOne requires internet connectivity to communicate with AI providers (Anthropic, OpenAI, Google). However, you can use local models via Ollama or LM Studio for offline usage.

Can I use AgentOne with my existing codebase?

Absolutely! AgentOne is designed to work with existing projects. It analyzes your current code patterns, architecture, and conventions to generate contextually appropriate solutions.

What programming languages does AgentOne support?

AgentOne supports all major programming languages including JavaScript, TypeScript, Python, Java, C++, Go, Rust, PHP, Ruby, and many others. It automatically detects your project's language and frameworks.

How much does AgentOne cost to use?

AgentOne itself is free for individual developers. You only pay for the API usage from your chosen AI provider (Anthropic, OpenAI, etc.). Typical costs range from $10-50/month depending on usage.

Can AgentOne work offline?

AgentOne can work with local LLM servers like Ollama, LM Studio, or other OpenAI-compatible endpoints running locally. This enables offline usage with reduced capabilities.

🔧 Features & Capabilities

What is Maestro Mode and when should I use it?

Maestro Mode is AgentOne's advanced reasoning system that breaks complex tasks into phases: analysis, planning, execution, and validation. Use it for complex refactoring, architecture changes, or multi-component features.

How does the Best Practices automation work?

Best Practices provides one-click automation for common development tasks like code formatting, testing, security analysis, and documentation generation. It automatically detects your project's tools and runs appropriate commands.

What are MCP servers and how do I use them?

MCP (Model Context Protocol) servers extend AgentOne's capabilities with custom tools and integrations. You can install community servers from the marketplace or create your own for specialized workflows.

Can AgentOne modify multiple files at once?

Yes, AgentOne can analyze and modify multiple files simultaneously while maintaining consistency across your codebase. All changes are presented for review before being applied.

How does the checkpoint system work?

AgentOne creates Git-based checkpoints before making significant changes. You can rollback to any checkpoint with one click. This requires Git to be initialized in your project.

Can AgentOne integrate with my CI/CD pipeline?

While AgentOne doesn't directly integrate with CI/CD, it can generate scripts and configuration files for various CI/CD platforms and help automate deployment workflows.

🔒 Security & Privacy

Is my code sent to AI providers?

Yes, relevant code context is sent to your chosen AI provider for analysis and generation. Always review your provider's privacy policy. Consider using local models for sensitive projects.

How can I protect sensitive information?

Use .gitignore patterns to exclude sensitive files, avoid including API keys or passwords in code selections, and consider using local LLM deployments for confidential projects.

Does AgentOne store my code locally?

AgentOne stores minimal temporary data locally for session management and checkpoints. No code is permanently stored or transmitted to Iterate.ai servers.

Can I use AgentOne in corporate environments?

Yes, but check with your security team first. Consider using local models or ensure your AI provider meets corporate security requirements. Enterprise licenses are available for additional compliance features.

What happens if AgentOne makes a mistake?

All changes require your approval before being applied. The checkpoint system allows instant rollback of any changes. AgentOne includes validation to prevent breaking changes.

Are there any security scanning features?

Yes, the Best Practices panel includes security analysis that can detect common vulnerabilities, dependency issues, and code quality problems with remediation suggestions.

🔍 Debugging Mode

When experiencing issues, enable debug mode for detailed logging and diagnostics.

1. Enable Debug Logging

Add to your VS Code settings:

{
  "AgentOne.debug": true,
  "AgentOne.verboseLogging": true
}

2. Check Output Panel

Open the Output panel in VS Code and select "AgentOne" from the dropdown to view detailed logs.

3. Collect System Information

Run this command in VS Code's Command Palette:

AgentOne: Generate Debug Report

🆘 Contact Support

Need additional help? Here are the best ways to get support:

📚

Documentation

Check this comprehensive documentation for detailed guides and examples.

Browse Docs
💬

Community Forum

Join discussions with other developers and get community support.

Visit Forum
🐛

Bug Reports

Report bugs or request features on our GitHub repository.

Report Issue
📧

Direct Support

Contact our support team directly for technical assistance.

Email Support

Still need help?

Our support team is here to help you get the most out of AgentOne.

Contact Support Join Community