Practical solutions for common issues when working with Maestro. This guide assumes you’re familiar with basic Maestro operations. For complete command reference, see Commands Reference. Need additional help? Email support@igent.ai

​
Manage Session Capacity

​
Reduce Capacity Usage

When you see capacity warnings or degraded performance: Option 1: Refresh to Latest Files (least aggressive) 
/refresh
Shows only latest file iterations, immediate relief. Option 2: Hide Old Iterations 
/hidefiles
Select experimental or old iterations to hide from context. Option 3: Compact Conversation 
/compact
Summarizes old dialog, preserves key decisions, frees capacity. Option 4: Remove Unnecessary Turns 
/forget
Remove conversation turns no longer needed. Option 5: Start Fresh (most aggressive) 
When session is too large:
1. /synopsis  (document current state)
2. Create new session
3. Upload synopsis to new session
4. Continue with clean capacity
Prevention: Use /refresh regularly, don’t accumulate unnecessary iterations, create focused sessions.

​
Fix Loading Issues

If session won’t load or times out:
  1. Refresh your browser page
  2. Clear browser cache
  3. Check internet connection
  4. Try a different browser
  5. Wait 30-60 seconds for very large sessions
  6. Contact support if the issue persists

​
Restore Missing Changes

If files or changes disappeared: 
"Show me all iterations of auth.py with timestamps"

"Restore auth.py to iteration 10"

"Display the full iteration history for config.yaml"

​
Fix File Issues

​
Find Missing Files

"List all Python files in the project"

"Search all files for the text 'class UserService'"

"Show me the directory structure under src/"
Check spelling and case sensitivity: 
"Check if the file is named Main.py or main.py"

​
Apply Pending Changes

If Maestro created proposals but files haven’t changed: 
"Apply the pending changes to the codebase"

"Show me the proposed changes, then apply them"
Maestro must use Apply Changes tool after creating proposals.

​
Recover from Wrong Iteration

"What iteration of auth.py am I currently viewing?"

"View auth.py iteration 15"

"Restore auth.py to iteration 15 (make it the current version)"

​
Fix File Syncing to Sandbox

Check if file is synchronized: 
"Check if myfile.py exists in the sandbox at /home/sandbox/src/myfile.py"

"Show me the contents of myfile.py as it appears in the sandbox"

"Is myfile.py in the .gitignore file?"
Move to synchronized location if needed: 
"Move myfile.py to /home/sandbox/src/ in the sandbox"

​
Resolve Sandbox Issues

​
Handle Unresponsive Sandbox

If commands timeout or no output appears: Option 1: Wait for Auto-Recovery (usually 30-60 seconds) Sandbox health monitoring attempts automatic remediation. Option 2: Check Resource Usage 
"Check CPU and memory usage in the sandbox"

"Show me what processes are running"

"Find any Python processes consuming excessive resources"
Option 3: Force Reset 
/reset-sandbox
Confirms before resetting. Files are preserved (in session storage), but running processes stop.

​
Stop Hung Commands

For commands that won’t complete: 
"Send Ctrl+C to the terminal to stop the running command"

"Close the terminal window called 'hung-process'"

"Show me what's running in the 'tests' terminal window"
If unresponsive: 
/reset-sandbox

​
Free Up Port 8080

"Show me what process is using port 8080"

"Kill the process using port 8080"

"Stop the server running on port 8080"
Alternative approach: 
"Start the server on port 3000 instead"

"Set up nginx to proxy from port 8080 to port 3000"

​
Fix Package Installation

Permission errors: 
"Install python3-pip using sudo apt-get"

"Install the package system-wide with sudo"
Package not found: 
"Update the apt package database, then install \{package\}"

"Search for \{package\} in Ubuntu repositories"

"Check if \{package\} is the correct name for Ubuntu"
Remember: Sandbox runs Ubuntu which uses apt-get.

​
Debug Tool Problems

​
Recover from Tool Failures

For validation errors: Maestro should see the error and retry. If stuck: 
"The tool validation failed. Review the error message and correct the input format."
For resource constraints: 
"Check sandbox resource usage - CPU and memory"

"Kill any processes consuming excessive resources"

"Try a lighter-weight approach to solve this"

​
Handle Merge Safety Warnings

When Maestro has pending proposals and tries to use another tool: Option 1: Apply Changes First (recommended) 
Confirm "Apply Changes first" to commit proposals, then run the tool
Option 2: Execute Anyway 
Confirm "Execute anyway" if using a read-only tool
Option 3: Cancel and Redirect 
Confirm "Cancel" and explain what to do instead
Best practice: Apply changes before using other tools.

​
Fix Tool Validation Errors

Maestro will show validation errors. If stuck: 
"Stop trying that approach. Let's use a different tool or method."

"The validation error says \{error\}. What's the correct parameter format?"

​
Troubleshoot Web and Network

​
Access Blocked URLs

For localhost URLs: 
"Deploy to the preview URL first, then access it"

"Start the server on port 8080 to make it publicly accessible"
For authenticated sites: 
"Activate the necessary secrets for authentication"
For rate-limited sites: 
"Wait a few minutes before retrying the request"

​
Fix Screenshot Failures

For localhost: 
"Start the server on port 8080 so it's publicly accessible via the preview URL"

"Take a screenshot of the preview URL once the server is running"
For sites blocking automation: 
Some sites detect automated browsers and block them. Try a different approach or manual verification.

​
Recover from Browser Operator Issues

If stuck or wrong page state: 
"Stop the browser automation. Let's use a simpler approach."

"Take a screenshot of the current page state so I can see what's happening"

"Navigate to \{URL\} directly instead of clicking through"

​
Fix Source Control Issues

​
Troubleshoot Clone Failures

Repository too large (>10GB limit): 
Contact support@igent.ai for special cases
Authentication failed: 
"Verify my GitHub account is linked" (check top-right menu)

"Check if I have access to this repository"
Branch not found: 
"List all branches in the repository"

"Clone from the default branch instead"

​
Fix PR Creation Problems

No changes detected: 
"Show me which files are modified in this session"

"Apply the pending changes before creating the PR"

"List files that have iterations newer than the base branch"
Branch name conflict: 
"Use a different branch name: feature/\{new-name\}"

"Update the existing PR instead of creating a new one"
Merge conflicts: 
"Pull the latest changes from the base branch"

"Show me the conflicting sections in \{file\}"

"Help me resolve the conflicts by reviewing both versions"

​
Handle Test and Validation Failures

​
Fix Missing Dependencies

"Install Python dependencies from requirements.txt"

"Install JavaScript dependencies from package.json using npm"

"Install pytest so I can run the Python tests"

​
Debug Failing Tests

Investigation approach: 
"Run the failing test and show me the complete error output"

"Explain what the test expects vs what's actually happening"

"Is the test wrong or is the implementation wrong?"
Never allow:
  • Skipping failing tests
  • Commenting out tests
  • Changing tests to match wrong implementation
Always require: 
"Understand why the test fails"

"Fix the root cause in the implementation"

"Ensure all tests pass before declaring complete"

​
Address Performance Regressions

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

Show me evidence at each step."

​
Restore Context and Memory

​
Recover Lost Information

If Maestro can’t remember something: 
"As I mentioned earlier, we're using PostgreSQL not MySQL"

"Check the DATABASE_URL in config.py for the database type"

"Review the synopsis to see what we've accomplished"
Or: 
/synopsis

​
Correct Misunderstandings

When Maestro acts on wrong assumptions: 
"Stop. That assumption is incorrect. 
\{Explain the actual situation\}
Please re-approach based on this correct understanding."
Prevention:
  • State constraints explicitly upfront
  • Provide complete context in initial request
  • Correct misunderstandings immediately

​
Repair Download and Export Issues

​
Fix Extraction Problems

When using /download-changed, the downloaded zip preserves the project’s directory structure. To integrate changes into your local project:
  1. Download the zip using /download-changed
  2. Navigate to your local project root directory
  3. Extract the zip there — files are structured to slot into the correct locations relative to the project root
If files end up in the wrong location, you likely extracted in a subdirectory instead of the project root. Re-extract at the top level of your project.

​
Verify Download Contents

Before downloading: 
"List all changed files so I can verify the download will be complete"

"Show me which files have new iterations"
After downloading, open the zip and verify all expected files are included and that .gitignored files are excluded.

​
Handle Large Session Downloads

For very large sessions, use more targeted downloads: 
/download-changed    (only modified files)

/download-recent     (5 most recently edited files)
Or ask Maestro to package specific files: 
"Package just the src/ directory for download"

"Download only the authentication-related files"

​
Debug Secrets and Integration

​
Fix Secret Activation Issues

"Show me which secrets are registered in Secret Manager"

"Are AWS secrets activated for this session?"

"Display the value of AWS_ACCESS_KEY_ID to verify it's correct"

​
Refresh OAuth Tokens

"The GitHub token expired. Refresh it in Secret Manager."

Or re-authorize: Secret Manager → Re-authorize GitHub

​
Handle Permission Errors

"The AWS operation failed with AccessDenied. 
Check the IAM policy for my credentials to see what permissions I have."

"Re-authorize the GitHub OAuth with broader scopes to access this resource"

​
Respond to Leaked Secrets

If a secret was accidentally committed to a file: Immediate actions:
  1. Ask Maestro: “Remove the secret from all files immediately”
  2. Do NOT create a PR or push to GitHub
  3. Regenerate the secret in the provider (consider it compromised)
  4. Register the new secret in Secret Manager
  5. Update applications with the new secret
Prevention: Always use environment variables. Never hardcode secrets. Use .gitignore for config files with secrets.

​
Use Recovery Tools

​
Reset Sandbox

When sandbox is unresponsive or misconfigured: 
/reset-sandbox
Confirms before proceeding. Files are preserved (in session), but sandbox state is lost (running processes, installed packages, environment variables).

​
Reload Session

For session issues:
  1. Refresh browser completely
  2. Clear browser cache if needed
  3. Session state should restore automatically
  4. Contact support if issues persist

​
Start New Session

As last resort:
  1. Use /synopsis to document current state
  2. Use /download-all to backup files
  3. Create new session
  4. Upload files and synopsis to new session
  5. Resume work with clean state

​
Prevent Future Issues

​
Maintain Sessions Proactively

Every 20-30 turns: 
/refresh (clean file view)

Check capacity bar in UI

/compact if capacity is getting high
Every major milestone: 
/synopsis (document progress)

/download-changed (backup current work)

​
Communicate Clearly

Upfront:
  • State all constraints explicitly
  • Provide complete context
  • Define success criteria
  • Set quality standards
During work:
  • Correct misunderstandings immediately
  • Provide feedback frequently
  • Challenge assumptions early
After work:
  • Validate thoroughly
  • Document learnings
  • Package deliverables

​
Validate Systematically

Never skip:
  • Running the full test suite
  • Checking performance benchmarks
  • Verifying edge cases
  • Reviewing all changes
The cost of validation is minutes. The cost of undetected issues is hours or days.

​
Get Additional Help

​
Self-Service Resources

"I'm having trouble with \{X\}. How do I fix this?"
Maestro has extensive knowledge of its own system and can often help troubleshoot. Search documentation for:
  • Relevant how-to guides
  • Reference material
  • Explanation pages

​
Contact Support

Email: support@igent.ai Effective bug reports include:
  • What you were trying to accomplish
  • What you expected to happen
  • What actually happened
  • Steps to reproduce
  • Session ID (if applicable)
  • Screenshots or error messages
  • Your current plan (if relevant)

​
Next Steps

Master troubleshooting, then explore: