Docs/Studio/Troubleshooting

Troubleshooting Predicate Studio

Common issues and solutions for Predicate 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:

Check your current plan in Dashboard
If on Hobby tier, click "Upgrade Plan"
Select Builder, Pro, Teams, or Enterprise
Complete payment
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.

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

Cause: Session expired or authentication token invalid.

Solution:

Sign out completely
Clear browser cookies for predicatesystems.ai
Sign in again
Try accessing Studio

If issue persists:

Try a different browser
Check browser console for errors
Contact support with error details

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 = PredicateAgent(
    api_key="your_key",
    enable_tracing=True  # ← Must be True
)

// TypeScript SDK
const agent = new PredicateAgent({
    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:

Builder: 30 days
Pro: 90 days
Teams: 180 days
Enterprise: Custom

Solution: Run a new agent with tracing enabled.

4. Wrong Account

You might be signed into a different account.

Solution:

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

Traces Not Loading

Problem: Trace List shows loading spinner indefinitely

Cause: Network issue or API timeout

Solution:

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

If persists:

Check status page for outages
Try again in 5-10 minutes
Contact support if issue continues

Trace Cards Look Broken

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

Cause: CSS loading issue or browser compatibility

Solution:

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

Supported browsers:

✅ Chrome 90+
✅ Edge 90+
✅ Firefox 88+
✅ Safari 14+

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:

Check browser console for errors
Try opening a different trace
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:

Run ID is incorrect
Trace was deleted (retention period expired)
Trace belongs to different account

Solution:

Verify Run ID is correct
Check trace age (may be expired)
Ensure you're signed into correct account

2. Network Error

Error message:

Failed to load trace. Network error occurred.

Causes:

Internet connection lost
API server timeout
Large trace file (>100MB)

Solution:

Check internet connection
Refresh the page
Wait a few minutes and try again
For very large traces, loading may take 30-60 seconds

3. Corrupted Trace Data

Error message:

Invalid trace format. Trace data may be corrupted.

Cause: Trace file is incomplete or malformed

Solution:

This trace cannot be recovered
Re-run the agent to generate a new trace
Contact support with Run ID for investigation

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:

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

3. Missing Screenshots

Some steps may not have screenshots if:

Screenshot capture failed during execution
Step executed too quickly
Agent configuration disabled screenshots

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:

Clear browser cache
Disable browser extensions (ad blockers, privacy tools)
Try incognito mode

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:

Refresh the page
Click a different step
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:

Bounding boxes: Require action execution
Diff: Requires snapshot events
Heatmap: Requires element importance scores

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

3. JavaScript Error

Solution:

Check browser console for errors
Refresh the page
Try a different browser

Playback Not Working

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

Cause: Playback controls JavaScript error

Solution:

Refresh the page
Use keyboard shortcuts (arrow keys) instead
Manually click through steps
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:

Use Fast Mode when possible (don't enable Diff overlay)
Disable unused overlays
Reduce playback speed
Navigate step-by-step instead of auto-play

2. Slow Browser/Computer

Solution:

Close other browser tabs
Close other applications
Use a modern browser (Chrome/Edge recommended)
Upgrade computer RAM if possible

3. Slow Internet

Solution:

Wait for all screenshots to download before browsing
Use wired connection instead of WiFi
Disable auto-play (use manual navigation)

PDF Export Issues

Export Button Doesn't Work

Problem: Clicking "Export PDF" does nothing

Cause: JavaScript error or browser popup blocker

Solution:

Check browser console for errors
Allow popups for predicatesystems.ai
Try a different browser
Refresh and try again

Export Takes Forever

Problem: PDF export shows loading spinner for minutes

Cause: Large trace with screenshots enabled

Expected times:

Small trace (10 steps, no screenshots): 5-10 seconds
Medium trace (30 steps, with screenshots): 30-60 seconds
Large trace (100 steps, with screenshots): 2-5 minutes

Solution:

Be patient for large traces
Disable screenshots to speed up export
Export smaller sections if possible

Export Fails

Problem: Export shows error message

Error: "Failed to generate PDF"

Causes:

Browser memory limit reached
Trace too large (>500 steps)
Network timeout

Solution:

Try exporting without screenshots
Export smaller traces
Try a different browser
Contact support for very large traces

PDF Missing Screenshots

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

Cause: Screenshots not fully downloaded yet

Solution:

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

Data & Performance Issues

Trace Data Incomplete

Problem: Some steps are missing data in Detail Panel

Possible reasons:

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

Solution:

For Fast Mode: Click the step to load full data
For crashes: Re-run the agent
For corruption: Contact support with Run ID

Token Usage Shows 0

Problem: LLM token usage shows 0 or is missing

Cause: Older trace format or LLM caching

Solution:

New traces should include token data
Cached LLM responses may show 0 tokens (expected)
Older traces may not have tracked tokens

Missing Bounding Boxes

Problem: Bounding box overlay shows no boxes

Cause: Step didn't include element interactions

Expected for:

Navigation steps
Scroll steps
Steps that don't target specific elements

Unexpected for:

Click steps
Type steps

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:

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

Solution:

Check if action should have changed the page
Verify verification signals in Detail Panel
This may be expected behavior

Browser-Specific Issues

Safari Issues

Problem: Features not working in Safari

Known issues:

Some CSS effects may not display correctly
PDF export may be slower
Screenshot rendering may differ

Solution:

Update Safari to latest version (14+)
Try Chrome or Edge for better compatibility
Report issues to support

Firefox Issues

Problem: Overlays flicker or render incorrectly

Solution:

Update Firefox to latest version (88+)
Disable hardware acceleration in Firefox settings
Try Chrome or Edge if issues persist

Mobile Browser Issues

Problem: Studio doesn't work well on mobile

Important: Studio is designed for desktop use.

Limitations on mobile:

Small screen makes interface cramped
Touch gestures may not work correctly
Screenshots hard to view
Performance issues

Solution:

Use desktop browser for best experience
If mobile is necessary, use landscape mode
Consider using tablet instead of phone

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:

Run ID (if applicable)
Browser & version (Chrome 120, Safari 14, etc.)
Operating System (Windows 11, macOS 14, etc.)
Screenshot of error (if visible)
Console errors (from step 1)
Steps to reproduce (what you clicked, what happened)

3. Contact Support

Email: support@sentienceapi.com

Include:

Subject: "Studio Issue: [brief description]"
All information from step 2
Your account email
When the issue started

4. Check Status Page

Visit status.predicatesystems.ai 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:

Internet connection speed
Browser version (update if old)
Computer memory (close other apps)
Trace size (very large traces are slower)

Use Artifacts To Debug

Predicate Vault

Troubleshooting Predicate Studio

Access Issues

Cannot Access Studio

Redirected to Dashboard

"Sign In Required" Message

Trace List Issues

No Traces Showing

1. Tracing Not Enabled

2. Recent Runs Only

3. Old Traces Deleted

4. Wrong Account

Traces Not Loading

Trace Cards Look Broken

Trace Debugger Issues

Trace Won't Open

"Error Loading Trace"

1. Trace Not Found (404)

2. Network Error

3. Corrupted Trace Data

Screenshots Not Loading

1. Screenshots Still Downloading

2. Network Timeout

3. Missing Screenshots

4. CORS or Security Error

Detail Panel Empty

Overlays Not Working

1. Full Trace Not Loaded

2. No Overlay Data Available

3. JavaScript Error

Playback Not Working

Slow Performance

1. Large Trace

2. Slow Browser/Computer

3. Slow Internet

PDF Export Issues

Export Button Doesn't Work

Export Takes Forever

Export Fails

PDF Missing Screenshots

Data & Performance Issues

Trace Data Incomplete

Token Usage Shows 0

Missing Bounding Boxes

Diff Overlay Shows No Changes

Browser-Specific Issues

Safari Issues

Firefox Issues

Mobile Browser Issues

Getting Help

1. Check Browser Console

2. Gather Information

3. Contact Support

4. Check Status Page

Common Error Messages

Performance Benchmarks