Troubleshooting

​

Need Help?

​

Session and Capacity Issues

​

”Session capacity is full”

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

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

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
   

• Manage capacity proactively
• Use /refresh regularly
• Don’t accumulate unnecessary iterations
• Create focused sessions

​

”Session won’t load” or “Loading timeout”

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

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

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

​

Session state seems wrong

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

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

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

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

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

• Maestro created code proposals
• Files don’t reflect changes
• Sandbox doesn’t have new code

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

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

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

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

​

Files not syncing to sandbox

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

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

• Commands timeout
• No terminal output
• “Sandbox unavailable” message

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

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

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

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

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

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"

​

Tool Issues

​

”Tool execution failed”

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

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

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

​

Merge safety warnings

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

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

​

Tool validation errors

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

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

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

​

Web and Network Issues

​

”Failed to retrieve URL”

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

• 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

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

• 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

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

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

​

Source Control Issues

​

Clone failed

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

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

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

​

PR creation failed

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

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

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

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

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

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

​

Tests failing unexpectedly

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

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

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

​

Benchmarks show worse performance

"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"

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

​

Memory and Context Issues

​

”Can’t remember something we discussed”

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

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

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

Maestro will course-correct immediately

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

​

Download and File Export Issues

​

Downloaded files have wrong structure

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

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

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

Then download to confirm all included

​

Can’t download large session

• All downloads should work
• Large sessions may take time

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

​

Secrets and Integration Issues

​

Already covered in Integrations & Secrets

• 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
• Support email: support@igent.ai
• Bug reports: Issues on GitHub (if applicable)

​

Effective Bug Reports

• 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)

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”

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

• Restore Files
• /reset-sandbox
• Reload session
• Create new session

​

”Maestro forgot everything”

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

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”

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

"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

• Contradictory statements
• Repeating same mistakes
• Not incorporating feedback

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

** 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."

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

​

Maestro asks questions instead of researching

• User-specific preferences
• Business requirements
• Architectural choices

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

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

Maestro should use tools before asking

​

Performance Issues

​

Maestro seems slow

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

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

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

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

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

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

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

• FAQ: Frequently asked questions
• Best Practices: Production-ready patterns
• Billing: Understanding costs and plans