Aether

Troubleshooting

Common issues and solutions for Aether setup and usage.

Bridge Connection Issues

Bridge Won't Start

Symptoms:

  • Bridge executable doesn't run
  • Port already in use errors
  • Permission denied errors

Solutions:

  1. Check Port Availability

    1# Windows 2netstat -ano | findstr :7890 3netstat -ano | findstr :7891 4 5# macOS/Linux 6lsof -i :7890 7lsof -i :7891

  2. Run with Admin/Sudo

    • Windows: Right-click → Run as administrator
    • macOS/Linux: sudo ./aether-bridge-*

  3. Check Firewall

    • Ensure localhost connections aren't blocked
    • Add exception for Aether bridge

  4. Verify Binary Permissions (macOS/Linux)

    1chmod +x ./aether-bridge-*

Bridge Starts But Unity Can't Connect

Symptoms:

  • Unity shows connection errors
  • No [Aether] Connected message in console

Solutions:

  1. Start Bridge First

    • Bridge must be running before entering Play mode
    • Check terminal for "listening on 127.0.0.1:7890"

  2. Check Bridge Settings

    • Verify host is 127.0.0.1 (not localhost)
    • Verify port is 7890 (Unity) and 7891 (MCP)

  3. Check Unity Console

    • Look for connection error messages
    • Verify Aether SDK is installed correctly

  4. Restart Both

    • Stop bridge and Unity
    • Start bridge first, then Unity

MCP Client Issues

Cursor MCP Not Working

Symptoms:

  • Aether tools don't appear in Cursor
  • Connection errors in Cursor
  • Tools return errors

Solutions:

  1. Restart Cursor

    • Cursor requires restart after MCP config changes
    • Close completely and reopen

  2. Verify Configuration

    • Check .cursor/mcp.json syntax (valid JSON)
    • No trailing commas
    • Correct WebSocket URL: ws://localhost:7891

  3. Check Bridge is Running

    • Bridge must be running before starting Cursor
    • Verify port 7891 is listening

  4. Check Cursor Logs

    • View Cursor's developer console for MCP errors
    • Look for connection failures

Tools Not Appearing

Symptoms:

  • @aether commands don't work
  • Tools don't show in autocomplete

Solutions:

  1. Verify MCP Connection

    • Check Cursor's MCP server status
    • Verify bridge is running

  2. Test Connection

    • Try @aether snapshot in Cursor chat
    • Check for error messages

  3. Reconfigure MCP

    • Delete .cursor/mcp.json
    • Recreate with correct format
    • Restart Cursor

Unity SDK Issues

SDK Not Installing

Symptoms:

  • Import fails
  • Missing files after import
  • Compilation errors

Solutions:

  1. Check Unity Version

    • Requires Unity 2021.3 LTS or newer
    • Verify your Unity version

  2. Re-import Package

    • Delete Assets/Aether/ if it exists
    • Re-import the .unitypackage

  3. Check for Errors

    • Review Unity Console for import errors
    • Fix any dependency issues

SDK Installed But Not Working

Symptoms:

  • No Aether menu in Unity
  • No connection to bridge
  • No events captured

Solutions:

  1. Verify Installation

    • Check Assets/Aether/ directory exists
    • Verify Aether.cs is present

  2. Check Compilation

    • Ensure no compilation errors
    • Fix any script errors

  3. Check Settings

    • Open Aether Settings (Aether → Settings)
    • Verify bridge host/port

Domain Reload Issues

Symptoms:

  • Aether disconnects on script recompile
  • Connection lost during play mode

Solutions:

  1. Auto-Reconnect

    • Aether automatically reconnects on domain reload
    • Wait a few seconds after recompile

  2. Disable Domain Reload (Optional)

    • Project Settings → Editor → Enter Play Mode Options
    • Disable "Domain Reload"
    • Note: May affect other workflows

macOS-Specific Issues

Gatekeeper Blocking Binary

Symptoms:

  • "Cannot be opened because it is from an unidentified developer"
  • Binary won't execute

Solutions:

  1. Allow in System Settings

    • System Settings → Privacy & Security
    • Click "Open Anyway" for the binary

  2. Remove Quarantine Attribute

    1xattr -d com.apple.quarantine ./aether-bridge-darwin-*

  3. Right-Click Open

    • Right-click binary → Open
    • Click "Open" in dialog

No Events Showing

Symptoms:

  • Tools return empty results
  • No events in snapshots
  • Unity running but no data

Debugging Checklist:

  1. Unity in Play Mode?

    • Events only captured during Play mode
    • Verify Play mode is active

  2. Bridge Connected?

    • Check Unity Console for connection message
    • Verify bridge terminal shows activity

  3. Events Occurring?

    • Trigger some events (logs, errors)
    • Check if they appear in Unity Console

  4. Check Settings

    • Verify capture is enabled
    • Check event limits aren't too restrictive

  5. Test with Snapshot

    • Try @aether snapshot
    • Should return current game state

Performance Issues

High CPU Usage

Symptoms:

  • Unity performance degraded
  • High CPU when Aether active

Solutions:

  1. Reduce Capture Frequency

    • Aether Settings → Reduce capture rate
    • Increase event limits

  2. Limit Event Types

    • Disable unnecessary event capture
    • Focus on errors and key events

  3. Check Bridge

    • Bridge should use minimal resources
    • If high CPU, restart bridge

Memory Usage

Symptoms:

  • Memory growing over time
  • Out of memory errors

Solutions:

  1. Configure Limits

    • Set event storage limits
    • Enable automatic cleanup

  2. Clear Old Data

    • Delete old event storage
    • Location: {DataDirectory}/Aether/

Still Having Issues?

If you're still experiencing problems:

  1. Check Logs

    • Unity Console for SDK errors
    • Bridge terminal for connection issues
    • Cursor logs for MCP errors

  2. Verify Setup

  3. Get Help

PreviousRecipes