Docs/Studio/Troubleshooting

Troubleshooting Sentience Studio

Common issues and solutions for Sentience Studio.

Access Issues

Cannot Access Studio

Problem: Studio menu item is disabled or shows "Upgrade Required"

Cause: Studio is only available on Builder tier and above.

Solution:

  1. Check your current plan in Dashboard
  2. If on Hobby tier, click "Upgrade Plan"
  3. Select Builder, Pro, Teams, or Enterprise
  4. Complete payment
  5. Studio access activates immediately

Redirected to Dashboard

Problem: Clicking Studio redirects to dashboard with ?upgrade=studio parameter

Cause: Your plan tier doesn't include Studio access.

Solution:

Same as above - upgrade to Builder tier or higher.

"Sign In Required" Message

Problem: Studio shows "Sign In Required" even though you're logged in

Cause: Session expired or authentication token invalid.

Solution:

  1. Sign out completely
  2. Clear browser cookies for sentienceapi.com
  3. Sign in again
  4. Try accessing Studio

If issue persists:

Trace List Issues

No Traces Showing

Problem: Trace List is empty even though you've run agents

Possible causes & solutions:

1. Tracing Not Enabled

Check if tracing is enabled in your agent code:

# Python SDK
agent = SentienceAgent(
    api_key="your_key",
    enable_tracing=True  # ← Must be True
)

// TypeScript SDK
const agent = new SentienceAgent({
    apiKey: "your_key",
    enableTracing: true  // ← Must be true
});

2. Recent Runs Only

Traces take 5-30 seconds to appear after agent completes.

Solution: Wait 30 seconds and refresh the page.

3. Old Traces Deleted

Traces older than your retention period are automatically deleted:

Solution: Run a new agent with tracing enabled.

4. Wrong Account

You might be signed into a different account.

Solution:

  1. Check email shown in top-right corner
  2. Sign out and sign in with correct account
  3. Verify API key matches the account

Traces Not Loading

Problem: Trace List shows loading spinner indefinitely

Cause: Network issue or API timeout

Solution:

  1. Check browser console (F12) for errors
  2. Refresh the page (Ctrl+R or Cmd+R)
  3. Check internet connection
  4. Try incognito/private browsing mode
  5. Clear browser cache

If persists:

Trace Cards Look Broken

Problem: Trace cards display incorrectly (missing text, wrong layout)

Cause: CSS loading issue or browser compatibility

Solution:

  1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
  2. Clear browser cache
  3. Update browser to latest version
  4. Try a different browser

Supported browsers:

Trace Debugger Issues

Trace Won't Open

Problem: Clicking a trace card does nothing or shows error

Cause: Invalid trace data or missing trace file

Solution:

  1. Check browser console for errors
  2. Try opening a different trace
  3. Copy Run ID and contact support

Temporary workaround:

Navigate directly to:

/studio/[run_id]?goal=[your_goal]

"Error Loading Trace"

Problem: Trace Debugger shows error message

Possible causes & solutions:

1. Trace Not Found (404)

Error message:

Trace not found. This trace may have been deleted or does not exist.

Causes:

Solution:

2. Network Error

Error message:

Failed to load trace. Network error occurred.

Causes:

Solution:

3. Corrupted Trace Data

Error message:

Invalid trace format. Trace data may be corrupted.

Cause: Trace file is incomplete or malformed

Solution:

Screenshots Not Loading

Problem: Screenshot viewer shows blank or loading spinner

Possible causes & solutions:

1. Screenshots Still Downloading

Indicator: Progress bar showing "Loading screenshots X/Y"

Solution: Wait for screenshots to finish downloading. Large traces with many steps may take 1-2 minutes.

2. Network Timeout

Solution:

  1. Check internet connection speed
  2. Refresh the page to restart download
  3. Try a different network (if on mobile/wifi)

3. Missing Screenshots

Some steps may not have screenshots if:

Solution: This is expected behavior. Not all steps may have screenshots.

4. CORS or Security Error

Error in console:

Failed to load image: CORS policy blocked

Solution:

Detail Panel Empty

Problem: Detail Panel shows "Loading..." indefinitely

Cause: Byte-range fetch failed or timed out

Solution:

Studio automatically loads full trace after 5 seconds. If this doesn't happen:

  1. Refresh the page
  2. Click a different step
  3. Wait 10 seconds for automatic fallback

Manual fix: The full trace should load automatically. If not, contact support.

Overlays Not Working

Problem: Clicking overlay buttons (Box, Diff, Heatmap) does nothing

Possible causes & solutions:

1. Full Trace Not Loaded

Diff overlay requires full trace data.

Indicator: "Fast mode (index only)" badge in header

Solution: Click a step in the Detail Panel to trigger full trace load. Wait 5-10 seconds.

2. No Overlay Data Available

Some traces may not have overlay data:

Solution: This is expected if the trace doesn't include that data.

3. JavaScript Error

Solution:

  1. Check browser console for errors
  2. Refresh the page
  3. Try a different browser

Playback Not Working

Problem: Play button doesn't auto-advance through steps

Cause: Playback controls JavaScript error

Solution:

  1. Refresh the page
  2. Use keyboard shortcuts (arrow keys) instead
  3. Manually click through steps
  4. Check browser console for errors

Slow Performance

Problem: Trace Debugger is laggy or slow

Possible causes & solutions:

1. Large Trace

Traces with 100+ steps can be slow.

Solution:

2. Slow Browser/Computer

Solution:

3. Slow Internet

Solution:

PDF Export Issues

Export Button Doesn't Work

Problem: Clicking "Export PDF" does nothing

Cause: JavaScript error or browser popup blocker

Solution:

  1. Check browser console for errors
  2. Allow popups for sentienceapi.com
  3. Try a different browser
  4. Refresh and try again

Export Takes Forever

Problem: PDF export shows loading spinner for minutes

Cause: Large trace with screenshots enabled

Expected times:

Solution:

Export Fails

Problem: Export shows error message

Error: "Failed to generate PDF"

Causes:

Solution:

PDF Missing Screenshots

Problem: Exported PDF doesn't include screenshots even though "Include Screenshots" was checked

Cause: Screenshots not fully downloaded yet

Solution:

  1. Wait for screenshot prefetch to complete (progress bar)
  2. Verify screenshots are visible in viewer before exporting
  3. Try export again

Data & Performance Issues

Trace Data Incomplete

Problem: Some steps are missing data in Detail Panel

Possible reasons:

  1. Fast Mode: Full data loads when you click into a step
  2. Trace Incomplete: Agent crashed before completing
  3. Data Corruption: Rare, but trace file may be corrupted

Solution:

Token Usage Shows 0

Problem: LLM token usage shows 0 or is missing

Cause: Older trace format or LLM caching

Solution:

Missing Bounding Boxes

Problem: Bounding box overlay shows no boxes

Cause: Step didn't include element interactions

Expected for:

Unexpected for:

Solution: If click/type steps are missing boxes, this may indicate a tracing issue. Contact support.

Diff Overlay Shows No Changes

Problem: Diff overlay is blank (no green/red areas)

Possible reasons:

  1. Page didn't change: Action didn't modify the page (expected)
  2. No snapshot data: Trace doesn't include before/after snapshots
  3. Same content: Page reloaded but content is identical

Solution:

Browser-Specific Issues

Safari Issues

Problem: Features not working in Safari

Known issues:

Solution:

Firefox Issues

Problem: Overlays flicker or render incorrectly

Solution:

Mobile Browser Issues

Problem: Studio doesn't work well on mobile

Important: Studio is designed for desktop use.

Limitations on mobile:

Solution:

Getting Help

If your issue isn't listed here:

1. Check Browser Console

Press F12 (or Cmd+Option+I on Mac) and check the Console tab for errors. Share these errors with support.

2. Gather Information

Collect these details:

3. Contact Support

Email: support@sentienceapi.com

Include:

4. Check Status Page

Visit status.sentienceapi.com to check for ongoing outages or maintenance.

Common Error Messages

Quick reference for error messages:

| Error Message | Meaning | Solution | |--------------|---------|----------| | "Upgrade Required" | Plan doesn't include Studio | Upgrade to Builder+ | | "Trace not found" | Invalid Run ID or deleted | Check Run ID, verify account | | "Failed to load trace" | Network or API error | Refresh, check connection | | "Loading..." (stuck) | Data fetch timeout | Wait 10s or refresh | | "Invalid trace format" | Corrupted data | Re-run agent, contact support | | "Screenshot failed to load" | Network or CORS issue | Refresh, check network | | "Export failed" | PDF generation error | Try without screenshots |

Performance Benchmarks

Expected performance for reference:

| Operation | Expected Time | |-----------|--------------| | Trace List load | 1-3 seconds | | Open trace (Fast Mode) | 2-5 seconds | | Load full trace | 5-15 seconds | | Screenshot prefetch (20 steps) | 10-30 seconds | | Step navigation | Instant | | Overlay toggle | Instant | | PDF export (small) | 10-20 seconds | | PDF export (large) | 1-5 minutes |

If your times are significantly longer, check:

Previous
Trace List
Next
SDK Tracing