> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Common issues and solutions for working with Maestro.

## Need Help?

If you can't find a solution to your issue in this troubleshooting guide, reach out to our support team:

**Email**: [support@igent.ai](mailto:support@igent.ai)

We're here to help you get the most out of Maestro.

## Session and Capacity Issues

### "Session capacity is full"

**Symptoms**:

* Warning about token usage
* Maestro mentions capacity constraints
* Degraded performance

**Root causes**:

* Long conversation history
* Many files in view
* Multiple large files
* Accumulated iteration history

**Solutions** (in order of least to most aggressive):

1. **Refresh files** to latest only:
   ```
   /refresh
   Immediate relief if many file iterations
   ```

2. **Hide experimental iterations**:
   ```
   /hidefiles
   Select old/experimental iterations to hide
   ```

3. **Compact memories**:
   ```
   /compact
   Summarizes old dialog, preserves key decisions
   ```

4. **Forget unnecessary turns**:
   ```
   /forget
   Remove turns no longer needed
   ```

5. **Start new session**:
   ```
   If session too large, consider fresh start:
   - /synopsis to document current session
   - Create new session
   - Upload synopsis
   - Continue with clean capacity
   ```

**Prevention**:

* Manage capacity proactively
* Use `/refresh` regularly
* Don't accumulate unnecessary iterations
* Create focused sessions

### "Session won't load" or "Loading timeout"

**Causes**:

* Very large session state
* Network connectivity issues
* Server-side restoration issues

**Solutions**:

1. Refresh browser page
2. Clear browser cache
3. Check internet connection
4. Try different browser
5. Contact support if persists

**For very large sessions**:

* May take 30-60 seconds to load
* Be patient during restoration
* Consider session size management

### Session state seems wrong

**Symptoms**:

* Files you created are missing
* Changes disappeared
* Conversation history incomplete

**Causes**:

* Browser cache issues
* Multiple tabs/sessions confusion
* Checkpoint restoration issue

**Solutions**:

1. Refresh browser

2. Check you're in correct session

3. Use file restore if needed:
   ```
   "Restore auth.py to iteration 10"
   Maestro uses Restore Files tool
   ```

4. Check iteration history:
   ```
   "Show me all iterations of auth.py"
   Verify expected iterations exist
   ```

## File and Code Issues

### "File not found" when Maestro tries to view

**Causes**:

* Typo in filepath
* File in wrong directory
* File not created yet
* Case sensitivity issue

**Solutions**:

```
1. List files to find correct path:
   "List all Python files in the project"

2. Search for file by content:
   "Search all files for 'class UserService'"

3. Check exact spelling and case:
   Filepaths are case-sensitive
   src/Main.py ≠ src/main.py
```

### Proposals not applied

**Symptoms**:

* Maestro created code proposals
* Files don't reflect changes
* Sandbox doesn't have new code

**Cause**: Apply Changes not invoked

**Solution**:

```
Maestro MUST use Apply Changes tool after all proposals

If you see proposals but no changes:
"Apply the pending changes to the codebase"

Maestro will invoke Apply Changes tool
```

### Code changes disappeared

**Likely cause**: Working on wrong iteration

**Check**:

```
"What iteration of auth.py am I viewing?"
"Show me all iterations of auth.py with timestamps"
```

**Solution**:

```
View correct iteration:
"View auth.py iteration 15"

Or restore if needed:
"Restore auth.py to iteration 15"
```

### Files not syncing to sandbox

**Check**:

1. Is file under synchronized paths?
2. Is file type synchronized (text-based)?
3. Is file .gitignored?

**Solutions**:

```
Ask Maestro to:
"Check if myfile.py is in the sandbox at /home/sandbox/src/myfile.py"
"Move myfile.py to /home/sandbox/src/ in the sandbox"
"Check if myfile.py is in .gitignore"
"Show me the contents of myfile.py in the sandbox"
```

## Sandbox Issues

### Sandbox not responding

**Symptoms**:

* Commands timeout
* No terminal output
* "Sandbox unavailable" message

**Solutions**:

1. **Wait for auto-recovery**:
   * Sandbox health monitoring active
   * Automatic remediation attempts
   * Usually recovers in 30-60 seconds

2. **Force reset**:
   ```
   /reset-sandbox
   Confirms your intent
   Terminates and recreates sandbox
   Files preserved (they're in session)
   ```

3. **Check resource consumption**:
   ```
   Ask Maestro to:
   "Check CPU and memory usage in the sandbox with htop"
   "Find any runaway Python processes"
   "Kill process [PID] if it's consuming too many resources"
   ```

### Command hangs or times out

**Causes**:

* Command genuinely taking long time
* Process waiting for input
* Infinite loop or deadlock

**Solutions**:

1. **For expected long commands**:
   ```
   Be patient
   Check terminal stream for progress
   Use Check Terminal Window to monitor
   ```

2. **For hung commands**:
   ```
   Use Terminal Operator to send Ctrl+C
   Or close terminal window
   Or /reset-sandbox if unresponsive
   ```

3. **Prevention**:
   ```
   For potentially long commands, ask Maestro to:
   "Run this command with a 5-minute timeout: [command]"
   "If the command takes longer than 5 minutes, cancel it"
   ```

### Port 8080 already in use

**Cause**: Previous server not stopped

**Solution**:

```
Ask Maestro to:
"Find what process is using port 8080"
"Kill the process using port 8080"

Or:
"Start the server in a different terminal window"
"Use port 3000 instead of 8080"
```

### Package installation fails

**Common issues**:

**Permission denied**:

```
Error: Permission denied
Solution: Ask Maestro to "Install [package] with sudo using apt-get"
Example: "Install python3-pip with sudo"
```

**Package not found**:

```
Solutions: Ask Maestro to:
"Update apt package database, then install [package]"
"Check if [package] is the correct package name for Ubuntu"
"Search for [package] in the Ubuntu repositories"
```

**Note**: Sandbox runs **Ubuntu** which uses `apt-get` package manager.

## Tool Issues

### "Tool execution failed"

**Common causes and solutions**:

**Invalid tool input**:

```
Cause: Validation error in JSON
Solution: Maestro should see error and retry with corrected input
If stuck: Point out the validation error
```

**Tool not available**:

```
Cause: Tool disabled for session
Check: /tools to see available tools
Solution: Enable tool if needed
```

**Resource constraints**:

```
Cause: Sandbox out of memory/CPU
Solution:
- Free resources (kill processes)
- Use lighter-weight approach
- Split into smaller operations
```

### Merge safety warnings

**What are they**:

```
Maestro proposes changes but hasn't applied them yet
Tries to use another tool
System detects potential for lost proposals
```

**Solutions presented**:

1. **Apply Changes first** (recommended):
   * Commits pending proposals
   * Then runs intended tool

2. **Execute anyway**:
   * Proceeds with tool
   * Proposals still pending
   * Acceptable for read-only tools

3. **Cancel and provide feedback**:
   * Cancels tool execution
   * You explain what to do instead

**Best practice**: Apply changes before using other tools to avoid warnings.

### Tool validation errors

**Maestro will tell you**:

```
Tool invocation has validation error:
[Specific error message]
Cross reference with tool schema and correct the input.
```

**What to do**:

* Read the error carefully
* Check tool schema for correct parameters
* Verify JSON structure
* Maestro should auto-correct on next attempt

**If Maestro keeps failing**:

```
"Stop trying that approach. Let's use a different tool or manual method."
```

## Web and Network Issues

### "Failed to retrieve URL"

**Causes**:

* URL requires authentication
* URL is localhost (not accessible from web tools)
* Rate limiting
* Server down

**Solutions**:

* For localhost: Use sandbox tools instead
* For auth: Provide secrets if possible
* For rate limits: Wait and retry
* For down servers: Verify URL is correct

### Screenshot tool fails

**Causes**:

* URL not publicly accessible (localhost, private network)
* Site blocks automated browsers
* JavaScript rendering errors

**Solutions**:

* For localhost: Deploy to preview URL first, then screenshot
* For blocked sites: Some sites detect automation; may not work
* For render errors: Check browser console logs

### Browser operator stuck

**Symptoms**:

* Browser operator not completing
* Timeout errors
* Wrong page state

**Solutions**:

* Simplify the goal
* Break into smaller steps
* Use explicit navigation instructions
* Try screenshot + manual analysis instead

## Source Control Issues

### Clone failed

**Repository too large**:

```
Error: Repository exceeds size limit
Current limit: ~10GB
Solution: Contact support or clone subset
```

**Authentication failed**:

```
Error: Unable to authenticate
Solution:
- Verify GitHub account linked
- Check repository exists
- Ensure you have access
```

**Branch not found**:

```
Error: Branch 'develop' does not exist
Solution:
- Verify branch name (case-sensitive)
- Try default branch
- Check branch exists on remote
```

### PR creation failed

**No changes detected**:

```
Cause: No files modified or selected
Solution:
- Verify files were changed
- Ensure Apply Changes ran
- Select changed files in PR UI
```

**Branch conflict**:

```
Error: Branch 'feature/auth' already exists
Solutions:
- Use different branch name
- Update existing PR instead
- Delete remote branch first (if safe)
```

**Merge conflict**:

```
Error: Cannot merge due to conflicts
Current limitation: No automated resolution
Solution:
- Pull latest changes (overwrite clone)
- Manually resolve via Maestro guidance
- Or push directly and resolve on GitHub
```

## Test and Validation Issues

### Tests won't run

**Common causes**:

**Dependencies missing**:

```
Error: Module not found
Solution: Ask Maestro to:
"Install Python dependencies from requirements.txt"
"Install npm dependencies from package.json"
```

**Wrong Python environment**:

```
Solution: Sandbox uses system Python with default venv
No need to create separate environment
If environment issues: "Verify Python environment setup in the sandbox"
```

**Test framework not installed**:

```
Solution: Ask Maestro to:
"Install pytest for running Python tests"
"Install jest as a dev dependency for JavaScript tests"
```

### Tests failing unexpectedly

**Investigation process**:

```
1. Read full error output carefully
2. Understand what test expects
3. Check if test or implementation is wrong
4. Fix the correct component
5. Verify all tests pass
```

**Don't let Maestro**:

* Skip failing tests
* Comment out tests
* Change tests to match wrong implementation

**Do require Maestro to**:

* Understand why tests fail
* Fix root cause
* Ensure all tests pass

### Benchmarks show worse performance

**After optimization attempt**:

**Investigate**:

```
"The optimization made performance worse. Let's understand why:
1. Profile both implementations
2. Compare execution paths
3. Identify what caused slowdown
4. Revert change
5. Try different optimization approach"
```

**Verification**:

```
Always compare to baseline
Use identical test conditions
Run multiple iterations
Account for variance
```

## Memory and Context Issues

### "Can't remember something we discussed"

**Causes**:

* Information was forgotten/compacted
* Happened many turns ago
* Context limit reached

**Solutions**:

```
Provide the information again:
"As I mentioned earlier, we're using PostgreSQL not MySQL"

Or reference files:
"Check the DATABASE_URL in config.py for database type"

Or use synopsis:
"/synopsis to review what we've done"
```

### Maestro misunderstands context

**When Maestro acts on wrong assumption**:

**Immediate correction**:

```
"Stop. That's not correct. [Explain the actual situation]. Please re-approach based on this correct understanding."

Maestro will course-correct immediately
```

**Prevention**:

* Be explicit about constraints upfront
* Provide context in initial request
* Correct misunderstandings early

## Download and File Export Issues

### Downloaded files have wrong structure

**Cause**: Extraction at wrong location

**Solution**:

```
For /download-changed:
Extract zip at your PROJECT ROOT (not inside a subdirectory)

Example workflow:
1. Download the zip file
2. Navigate to your project root: cd ~/my-project
3. Extract there: unzip maestro_changes_*.zip

Files will slot into their correct locations relative to project root
```

### Zip file seems incomplete

**Check**:

* Did you use correct download type?
* Are files .gitignored?
* Were files actually changed?

**Verify**:

```
Before download:
"List all changed files"
Verify expected files are present

Then download to confirm all included
```

### Can't download large session

**Current behavior**:

* All downloads should work
* Large sessions may take time

**If timeout occurs**:

* Use /download-changed (smaller subset)
* Or /download-recent (just latest files)
* Or specify specific files

## Secrets and Integration Issues

### Already covered in [Integrations & Secrets](../getting-started/integrations-secrets)

**Quick reference**:

* Secret not working → Check registration and activation
* OAuth expired → Refresh in Secret Manager
* Permission denied → Check scopes/permissions
* Accidentally committed → Rotate immediately

## Getting Help

### Self-Service

1. **Ask Maestro**:
   ```
   "I'm having trouble with [X]. How do I fix this?"
   Maestro has extensive knowledge of its own system
   ```

2. **Search documentation**:
   ```
   Use documentation search
   Check relevant section (Sandbox, Source Control, etc.)
   ```

3. **Review examples**:
   ```
   Working examples often clarify confusion
   Check Quick Start and Session Strategies
   ```

### Community and Support

* **Documentation**: [https://docs.igent.ai](https://docs.igent.ai)
* **Support email**: [support@igent.ai](mailto:support@igent.ai)
* **Bug reports**: Issues on GitHub (if applicable)

### Effective Bug Reports

**Include**:

* What you were trying to do
* What you expected to happen
* What actually happened
* Steps to reproduce
* Session ID (if applicable)
* Screenshots or error messages
* Your plan (if relevant)

**Example**:

```
Issue: Sandbox won't start

Expected: Sandbox starts when I run first command
Actual: Timeout error after 60 seconds

Steps:
1. Start new session
2. Request: "Install Python package xyz"
3. Maestro tries Execute Command
4. Times out

Session ID: abc-123-def-456
Error: [paste error message]
Plan: Basic (if relevant)
```

## Common Misconceptions

### "I broke Maestro"

**Reality**: Almost everything is recoverable:

* Files have iteration history (restore any version)
* Sessions checkpoint automatically
* Sandbox can be reset
* Secrets are isolated

**Recovery tools**:

* Restore Files
* `/reset-sandbox`
* Reload session
* Create new session

### "Maestro forgot everything"

**Reality**: Information persists in different forms:

* Dialog in memories
* Decisions in file content
* Clone records (never forgotten)
* Iteration history

**Access forgotten context**:

```
View old iterations for implementation details
Clone records show which repos/branches
File diffs show what changed and when
```

### "This will take forever to fix"

**Reality**: Maestro is designed for iteration:

* Fast failure and correction cycles
* Can try multiple approaches quickly
* Learns from failures
* Often finds solutions through systematic exploration

**Approach**:

```
"This isn't working. Let's step back:
1. What have we tried?
2. What failed and why?
3. What haven't we tried?
4. New approach recommendation"

Maestro will synthesize and propose better path
```

## Debugging Maestro Itself

### Maestro seems confused

**Symptoms**:

* Contradictory statements
* Repeating same mistakes
* Not incorporating feedback

**Solutions**:

1. **Clear correction**:
   ```
   "Stop. You're misunderstanding X. Here's the correct information: [clear explanation]"
   ```

2. **Reset context**:
   ```
   "/forget last 3 turns"
   Removes confusing interaction
   Start fresh with clarity
   ```

3. **Provide explicit constraints**:
   ```
   "For this implementation:
   - Use Python 3.11 (not 3.9)
   - PostgreSQL (not MySQL)
   - Pytest (not unittest)

   Confirm you understand before proceeding."
   ```

### Maestro making assumptions

**When Maestro assumes wrong things**:

```
** Don't let pass:
Maestro: "Using MySQL..."
(But you want PostgreSQL)

** Correct immediately:
You: "Stop. We're using PostgreSQL, not MySQL. Update all database code accordingly."
```

**Prevention**:

* State constraints explicitly
* Provide all relevant context upfront
* Correct assumptions immediately

### Maestro asks questions instead of researching

**Sometimes appropriate**:

* User-specific preferences
* Business requirements
* Architectural choices

**Sometimes inappropriate**:

* Technical information (use Perplexity Search)
* API documentation (use web tools)
* Best practices (use research tools)

**When inappropriate**:

```
You: "Use Perplexity Search to research the answer to your question, then proceed"

Maestro should use tools before asking
```

## Performance Issues

### Maestro seems slow

**Expected behavior**:

* Complex reasoning takes time
* Tool execution has inherent latency
* Validation is thorough (not instant)

**Genuine slowness**:

```
Check:
- Is session capacity very high? (Affects token processing)
- Is sandbox under heavy load? Ask Maestro to "Check sandbox resource usage"
- Is network slow? (Affects web tools)

Solutions:
- Manage capacity (/refresh, /compact)
- Free sandbox resources: "Kill any unnecessary processes in the sandbox"
- Use faster tools when appropriate
```

### Long response times

**For research-heavy requests**:

```
Expected:
- Perplexity Search (research mode): ~30 seconds
- Complex Reasoning: 1-3 minutes
- Browser Operator: Variable based on task

If longer than expected:
- Check if Maestro is stuck
- Cancel and simplify request
- Break into smaller parts
```

## When Nothing Works

### Nuclear Options

**Last resort solutions** (use sparingly):

1. **Reload session**:
   ```
   Refresh browser completely
   Clear browser cache if needed
   Session state should restore
   ```

2. **New session**:
   ```
   If session truly corrupted:
   - /synopsis to document current state
   - /download-all to preserve files
   - Start new session
   - Upload files and synopsis
   - Resume work
   ```

3. **Contact support**:
   ```
   For persistent issues:
   - Document problem thoroughly
   - Include session ID
   - Describe steps to reproduce
   - Contact support@igent.ai
   ```

## Prevention Better Than Cure

### Proactive Practices

**Regular maintenance**:

```
Every 20-30 turns:
- /refresh to clean file view
- Review capacity bar
- Consider /compact if high

Every major milestone:
- /synopsis to document
- /download-changed for backup
```

**Clear communication**:

```
Upfront:
- State all constraints
- Provide complete context
- Define success criteria
- Set quality standards

During:
- Correct misunderstandings immediately
- Provide feedback frequently
- Challenge assumptions early

After:
- Validate thoroughly
- Document learnings
- Package deliverables
```

**Defensive validation**:

```
Never skip:
- Running tests
- Checking benchmarks
- Verifying edge cases
- Reviewing all changes

Cost of validation: Minutes
Cost of undetected issues: Hours or days
```

## Next Steps

Troubleshooting mastered:

* **[FAQ](reference/faq)**: Frequently asked questions
* **[Best Practices](reference/best-practices)**: Production-ready patterns
* **[Billing](reference/billing)**: Understanding costs and plans