Troubleshooting

Comprehensive guide to solving common problems.

---

Installation

Installer won't run (Windows)

Symptoms: .msi file doesn't open or shows a security warning.

Solutions:

1. Right-click the file → Properties → check "Unblock" → OK → try again
2. If Windows SmartScreen blocks it — click "More info" → "Run anyway"
3. Make sure you downloaded from the official site: agentnine.ru/download
4. Try running as administrator

Installer won't run (macOS)

Symptoms: "Agent Nine can't be opened because it is from an unidentified developer."

Solutions:

1. Open System Preferences → Security & Privacy → General
2. You'll see "Agent Nine was blocked" — click "Open Anyway"
3. Alternatively: right-click the app → Open (this bypasses Gatekeeper for one launch)

Installer won't run (Linux)

Symptoms: AppImage doesn't launch.

Solutions:

1. Make the file executable: right-click → Properties → Permissions → "Allow executing"
2. Or via terminal: chmod +x AgentNine.AppImage && ./AgentNine.AppImage
3. For .deb: sudo dpkg -i agent-nine.deb && sudo apt-get install -f
4. Missing libraries: install libwebkit2gtk-4.0 and libssl3

App opens but shows a blank/white screen

Solutions:

1. Clear the app cache:
   • Windows: delete %APPDATA%/agent-nine/
   • macOS: delete ~/Library/Application Support/agent-nine/
   • Linux: delete ~/.config/agent-nine/
2. Check that your GPU drivers are up to date
3. Try launching with --disable-gpu flag

---

Authentication

Magic link email doesn't arrive

Solutions:

1. Check your spam/junk folder
2. Check that you typed your email correctly
3. Try again — the link expires in 10 minutes
4. If using corporate email, check with IT — some firewalls block transactional emails
5. Try a different email address (Gmail, Outlook usually work)

Magic link says "expired" or "invalid"

Causes:

• Links expire after 10 minutes
• Each link can only be used once
• Opening an old link after requesting a new one invalidates the old link

Solution: Request a new magic link and use it immediately.

"Session expired" error

Sessions expire after prolonged inactivity. Solution: Sign in again. Your chat history is preserved.

Can't sign in on multiple devices

Agent Nine supports multiple active sessions. If you can't sign in:

1. Check Settings → Account → Active Sessions
2. Make sure you haven't hit the session limit
3. Try revoking old sessions you're no longer using

---

Connection & Network

Agent Nine won't connect to the server

Symptoms: "Connection error", "Network unavailable", or infinite loading.

Solutions:

1. Check your internet connection — try opening any website
2. Check if agentnine.ru is accessible in your browser
3. If behind a corporate proxy or VPN:
   • Check that WebSocket connections are allowed
   • Port 443 (HTTPS) must be open
   • Ask IT to whitelist: *.agentnine.ru
4. Disable any ad blockers or browser extensions that might interfere
5. Try a different network (e.g., mobile hotspot)

Agent Nine is connected but very slow

Possible causes:

• High network latency — check with a speed test
• Large context (long conversation) — use /compact
• Server load during peak hours — try again later
• VPN adding latency — try without VPN

WebSocket connection keeps dropping

Solutions:

1. Check for unstable internet (Wi-Fi signal, mobile data)
2. Some corporate firewalls kill long-lived connections — ask IT about WebSocket policies
3. If using a proxy, make sure it supports WebSocket upgrade
4. Restart the app

---

Code Mode

"No machine connected"

Symptoms: You're in Code mode but Agent Nine says no machine is available.

Solutions:

1. Make sure the desktop app is running (not just the web app)
2. Check that you're signed in with the same account
3. Restart the desktop app
4. Check Settings → Account → Machines — your machine should appear in the list

Agent Nine doesn't see my project files

Solutions:

1. Open the correct project folder using the project picker (sidebar)
2. Make sure you're in Code mode, not Chat mode
3. Check that the folder path is correct and the folder exists
4. Large projects: Agent Nine reads files on demand — it doesn't scan everything upfront

Agent Nine reads the wrong files

Solutions:

1. Be more specific: "read src/auth/login.ts" instead of "read the login file"
2. Check that you're in the correct project (project name shown in sidebar)
3. If the project has multiple files with similar names, specify the full path

Commands fail with "Permission denied"

Solutions:

1. Check file/folder permissions
2. macOS: System Preferences → Security → Files & Folders → allow your terminal app
3. Linux: check ownership with ls -la, fix with chmod or chown
4. Windows: right-click app → Run as Administrator
5. Some folders are protected by the OS (e.g., Program Files, /usr/bin)

Agent Nine runs the wrong shell

Agent Nine auto-detects:

• macOS/Linux → Bash
• Windows → PowerShell

Solutions:

1. Specify explicitly: "run this using bash" or "use PowerShell"
2. If Bash isn't found on Windows, install Git Bash or WSL

Commands hang or timeout

Solutions:

1. Interactive commands (those waiting for user input) don't work — Agent Nine can't type into running processes
2. Commands that require y/n confirmation will hang — pass --yes or -y flag
3. If a build is too long, ask Agent Nine to run it in the background
4. Default timeout is 2 minutes — for longer commands, Agent Nine auto-extends to 10 minutes

Agent Nine made unwanted file changes

Immediate fix: Type /undo to revert all changes from the current session.

Prevention:

• Use the Default permission mode — approve each action
• Set up agentnine.md with rules like "never modify files in config/"
• Use hooks to block changes to specific files

---

Chat Mode

Code execution fails in cloud sandbox

Solutions:

1. The sandbox is isolated — no access to your local files
2. Install dependencies first: "install pandas and then run the script"
3. Supported runtimes: Python, Node.js, Go, Rust, Java
4. File size limits: keep files under 10 MB
5. Execution timeout: 2 minutes per command

"Sandbox unavailable" error

Solutions:

1. Try again — the sandbox may be temporarily overloaded
2. For simple code, ask Agent Nine to show the code instead of running it
3. Switch to Code mode if you need to run code locally

Generated code doesn't work

Tips:

1. Give Agent Nine more context about your project setup
2. Specify the language/framework version: "Python 3.11", "Node.js 20"
3. If the first attempt fails, paste the error — Agent Nine will fix it
4. For complex setups, start with a simpler version and iterate

---

Integrations

Integration won't connect

Solutions:

1. Allow popups in your browser — OAuth requires a popup window
2. Check that you have the right permissions on the external service
3. Try a different browser (Chrome recommended)
4. Clear cookies and try again
5. If behind VPN/proxy, the OAuth callback may be blocked — try without VPN

"Token expired" error

OAuth tokens expire periodically (usually every 1-2 hours).

Solution: Go to Settings → Integrations → disconnect the integration → reconnect it.

Integration returns empty results

Solutions:

1. Check that you have access to the requested resource
2. GitHub: Is the repo private? Make sure you authorized the correct organization
3. Notion: You must explicitly share pages with the Agent Nine integration during setup
4. Slack: Agent Nine can only see channels it's been invited to
5. Figma: Check that the file is shared with your account
6. Google Drive: "Shared with me" items need to be accepted first
7. Try being more specific: "list issues in the backend repo" instead of "show issues"

Integration actions fail

Solutions:

1. Check that your account has write permissions (for creating issues, sending messages, etc.)
2. Some organizations restrict third-party app permissions — check with your admin
3. Rate limits: if you make many requests quickly, wait a minute and retry
4. For GitHub: check that your token has the required scopes

Multiple accounts

If you have multiple accounts on the same service (e.g., personal and work GitHub):

1. Make sure you're logged into the correct account in your browser before connecting
2. To switch accounts: disconnect the integration, log into the other account in your browser, then reconnect

---

Voice Input

Microphone doesn't work

Solutions:

1. Browser permissions: Click the lock/mic icon in the address bar → allow microphone
2. macOS: System Preferences → Security & Privacy → Microphone → allow browser
3. Windows: Settings → Privacy → Microphone → allow the app
4. Linux: Check PulseAudio/PipeWire settings, ensure the mic is not muted
5. Make sure no other app is using the microphone (Zoom, Discord, etc.)
6. Try refreshing the page / restarting the app
7. Try a different microphone or headset

Microphone works but no transcription

Solutions:

1. Check your internet connection — transcription requires a server call
2. Speak for at least 1-2 seconds — very short audio may not be transcribed
3. The transcription indicator should animate while recording — if it's static, try clicking the mic icon again

Transcription is inaccurate

Tips:

• Move closer to the microphone
• Reduce background noise (fans, music, other people)
• Speak at a natural pace — not too fast, not too slow
• Pause briefly between sentences
• Technical terms may be misheard — edit before sending
• Try speaking in one language at a time (mixing languages reduces accuracy)

Voice input button is missing

Solutions:

1. Only available in desktop app and web app (not in all browsers)
2. If using an older browser, update to the latest version
3. Safari: make sure MediaRecorder API is enabled

---

Performance

Agent Nine is slow to respond

Possible causes and fixes:

Cause	Solution
Long conversation	Use /compact to compress history
Complex task	Normal — Agent Nine thinks longer for difficult problems
Large files in context	Reference specific files instead of entire directories
Network latency	Check your connection speed
Server load	Try during off-peak hours

High CPU/memory usage

Solutions:

1. Close unused sessions in the sidebar
2. Restart the app periodically for long work sessions
3. If the project is very large (>10k files), Agent Nine only reads files it needs — this is normal behavior
4. Update to the latest version — performance improvements are released regularly

Context keeps filling up

The AI context has a limited size. When it fills up:

1. /compact — compress the conversation (recommended)
2. /clear — start fresh (loses history)
3. Start a new session for a different task
4. Put persistent instructions in agentnine.md instead of repeating them

---

File Operations

Agent Nine can't find a file I know exists

Solutions:

1. Use the full path: "read src/components/Header.tsx"
2. Check the project root — Agent Nine searches from the project folder, not your home directory
3. The file might be in .gitignore — Agent Nine still reads it, but may not search for it proactively

Agent Nine overwrites my changes

Solutions:

1. Use /undo immediately to revert
2. If you have unsaved changes in your editor, save them before letting Agent Nine edit
3. Set the Default permission mode to approve each file edit
4. Agent Nine creates backup before editing — check your editor's undo history

Agent Nine creates files I didn't ask for

Solutions:

1. Be specific about what you want: "edit the existing file, don't create new files"
2. Set up agentnine.md with rules like "never create new files without asking"
3. Use hooks to get notified when files are created

---

Plan Mode

Plan mode doesn't seem to work

Solutions:

1. Type /plan to enter plan mode explicitly
2. In plan mode, Agent Nine only plans — it won't write code until you approve
3. The plan is saved in .agent-nine/plan.md in your project
4. To exit plan mode and start implementation, say "go ahead" or "implement the plan"

Plan is too vague

Tips:

1. Give more context about the task
2. Ask Agent Nine to break down specific steps: "be more specific about step 3"
3. Provide constraints: "we must maintain backwards compatibility"

---

Agents

Agent seems stuck or frozen

Solutions:

1. Check the status area — it may still be working on a complex task
2. Cancel the agent and restart the task
3. Break the task into smaller pieces
4. Agent timeout is typically 10-15 minutes for complex tasks

Agent produced incorrect results

Solutions:

1. Review the agent's output carefully
2. Use /undo if the agent made wrong file changes
3. Give more specific instructions next time
4. Use the Verification agent type to double-check results

Too many agents running

Solutions:

1. Cancel unnecessary agents from the status area
2. Be more specific — Agent Nine creates fewer agents for well-defined tasks
3. Each agent uses its own context and tokens — monitor usage in Settings

---

Account & Billing

Usage limit reached

Symptoms: "Quota exceeded" or "Rate limit" error.

Solutions:

1. Check your usage in Settings → Usage
2. Usage resets weekly
3. Use a lighter model (Haiku) for simple tasks to conserve quota
4. Use /compact to reduce token usage in long conversations
5. Upgrade your plan for higher limits

Can't delete account

Go to Settings → Account → Delete Account. This permanently deletes:

• Your account and profile
• All session history
• All integrations
• All machine connections

This action cannot be undone.

---

Updates

How to update Agent Nine

Platform	Update method
Windows	Download the latest .msi from agentnine.ru/download and install over the existing version
macOS	Download the latest .dmg and drag to Applications (replaces old version)
Linux	Download the latest AppImage or .deb
Web	Always up to date — just refresh the page

Update broke something

Solutions:

1. Your settings and chat history are preserved across updates
2. If the app crashes after update, clear the app cache (see "App opens but shows a blank/white screen" above)
3. Report the issue to support@agentnine.ru with your version number

---

Still Stuck?

Contact support at support@agentnine.ru with:

• What you were trying to do
• What happened instead (include error messages if any)
• Your platform (Windows/macOS/Linux)
• Desktop or web app
• Screenshots if possible