docs/implementation/OBSERVATORY_TROUBLESHOOTING.md

Observatory Troubleshooting Guide

Issue: Blank Page on Launch

Fixes Applied (2026-06-16)

1. Added Welcome Screen: When no run/task is selected, the app now shows a proper welcome screen with feature overview instead of just an error message.

2. Improved Error Handling: Added clearer warning messages when run/task data fails to load.

3. Better Initial State: The app now gracefully handles the initial render before any data is loaded.

How to Launch

Use the provided launch script:

./launch_observatory.sh

Or manually:

cd /workspace/ainn-cm-poc-data-agent
source .venv/bin/activate
streamlit run src/data_agent_baseline/observatory/app.py --server.port 8501

Access the App

• Local: http://localhost:8501
• External: http://138.108.24.100:8501 (if accessible)

Common Issues

1. Blank Page After Launch

Symptoms: Browser shows empty white/dark page

Solutions:

• Hard refresh the browser (Ctrl+Shift+R or Cmd+Shift+R)
• Clear browser cache
• Try a different browser
• Check browser console for JavaScript errors (F12 → Console tab)

2. "No runs found" Message

Symptoms: Sidebar shows "⚠️ No runs found"

Solutions:

• Check the artifact path in the sidebar Configuration expander
• Verify the path exists: /data3/dataFAIR/kdd-dev/public/artifacts/runs/
• Verify run folders exist in that path
• Click the refresh button after correcting the path

3. Welcome Screen Stuck

Symptoms: Shows welcome screen but selecting run/task doesn't load

Solutions:

• Check that the selected run folder contains:
  • Task subdirectories (task_XXX/)
  • comprehensive_evaluation.csv (optional but recommended)
• Check browser console for errors
• Try refreshing the page

4. CSS/Styling Issues

Symptoms: Page loads but styling looks wrong or content is hidden

Solutions:

• The Mission Control CSS is injected when the Mission Summary tab loads
• Try switching to the Mission Summary tab
• Check browser console for CSS errors
• Disable browser extensions that might interfere with styling

5. Port Already in Use

Symptoms: Error message "Port 8501 is not available"

Solutions:

# Kill existing Streamlit processes
pkill -f streamlit

# Or kill specific port
lsof -ti:8501 | xargs kill -9

# Then relaunch
./launch_observatory.sh

Verification Steps

Run these commands to verify everything is set up correctly:

# 1. Verify Python environment
source .venv/bin/activate
python3 -c "import streamlit; print(f'Streamlit version: {streamlit.__version__}')"

# 2. Verify Observatory imports
python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; print('✓ Imports OK')"

# 3. Verify artifact path
ls -la /data3/dataFAIR/kdd-dev/public/artifacts/runs/ | head -10

# 4. Check run count
python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; d=RunDiscovery(); runs=d.discover_runs(); print(f'{len(runs)} runs found')"

Expected Behavior

1. First Load: You should see a welcome screen with:

   • Title: "🔬 Agent Observatory"
   • Info message: "👈 Select a run and task from the sidebar"
   • Feature list
   • Quick start guide

2. After Selecting Run: The sidebar should show:

   • Current Context card with run details
   • Task dropdown populated with available tasks
   • Artifact status pills

3. After Selecting Task: The main content should show:

   • Mission Summary tab (default)
   • Hero header with gradient background
   • Executive summary card
   • KPI cards
   • Execution flow visualization

Debug Mode

To see more detailed logs:

streamlit run src/data_agent_baseline/observatory/app.py \
    --server.port 8501 \
    --logger.level=debug

Getting Help

If issues persist:

1. Check the Streamlit logs in the terminal
2. Check browser console (F12) for JavaScript errors
3. Verify all dependencies are installed: uv sync
4. Try the minimal test app: streamlit run test_streamlit_minimal.py --server.port 8503

Known Limitations

• First load may take 1-2 seconds for run discovery
• Large trace files (>10MB) may take longer to parse
• Some older runs may lack full metadata (gracefully degraded)
• CSS styling only applies after Mission Summary tab is viewed

Performance Tips

• Discovery is O(n) in number of runs — startup may be slower with 500+ runs
• Task loading includes trace parsing — may take 2-3 seconds for large traces
• Session state caching avoids re-loading on page interactions
• Switching between tasks reloads data — switching between tabs does not