Troubleshooting Guide

Quick Summary: Solutions to common problems and error messages you may encounter while using PEBL Hub.

What You'll Find

• Common error messages and their solutions
• Browser compatibility issues
• Data upload and download problems
• Study configuration issues
• Participant access problems
• When and how to contact support

Browser Issues

Problem: Test Won't Load

Symptoms: Blank screen, loading forever, or "Module failed to load" error

Common Causes:

• JavaScript disabled
• Browser too old
• Ad blocker interfering
• Pop-up blocker active

Solutions:

1. Check JavaScript is enabled:

• Chrome: Settings → Privacy and Security → Site Settings → JavaScript → Allowed
• Firefox: about:config → javascript.enabled → true
• Safari: Preferences → Security → Enable JavaScript

1. Update your browser:

• Chrome 90+ recommended
• Firefox 88+ recommended
• Safari 14+ recommended
• Edge 90+ recommended

1. Disable ad blockers (temporarily):

• uBlock Origin, AdBlock Plus can interfere with PEBL
• Add peblhub.online to whitelist

1. Allow pop-ups (if needed):

• Some tests may open in new windows
• Check browser address bar for blocked pop-up icon

1. Try incognito/private mode:

• Rules out extension conflicts
• Chrome: Ctrl+Shift+N (Cmd+Shift+N on Mac)
• Firefox: Ctrl+Shift+P (Cmd+Shift+P on Mac)

Problem: Test Runs But Data Doesn't Upload

Symptoms: Test completes but no data appears in Browse Data

Solutions:

1. Check browser console (F12 → Console tab):

• Look for red error messages
• Common errors:

- "Network request failed" → Internet connection issue

- "403 Forbidden" → Token/authentication problem - "CORS error" → Server configuration issue

1. Verify internet connection:

• Test must upload data at end
• Weak/unstable connection can cause failures
• Try again with stable connection

1. Check study token:

• Verify URL has correct token=STUDYxxx parameter
• Check study is active (not expired)

1. Try different browser:

• Rules out browser-specific issues

Problem: Participant Can't Access Study URL

Symptoms: 404 error, "Study not found", or blank page

Solutions:

1. Verify study is active:

• Go to My Research Studies
• Check study shows "Active" status
• Activate if needed

1. Check URL is complete:

• Must include ?token=STUDYxxx parameter
• Chain URLs must include ?chain=CHAINxxx&token=STUDYxxx
• No spaces or line breaks in URL

1. Test URL yourself first:

• Click "▶ Try it out" button
• If it works for you but not participants, may be:

- Firewall blocking participants

- Participant using incompatible browser - Copy/paste error in URL

1. Use short URLs:

• Less prone to copy/paste errors
• Generate with "🔗 Short URL" button

Study Configuration Issues

Problem: Parameters Not Saving

Symptoms: Click save but changes don't persist

Solutions:

1. Check you're logged in:

• Session may have expired
• Refresh page and log in again

1. Verify edit permissions:

• You must own the study or have edit access
• Check with study owner if it's a shared study

1. Check for errors:

• Browser console (F12) may show error
• Invalid parameter values can prevent saving

1. Try different browser:

• Rules out browser-specific issues

Problem: Test Chain Won't Load Next Item

Symptoms: Chain stops after one test, doesn't advance

Solutions:

1. Check chain configuration:

• Verify all items are included in chain
• Check for missing items or broken links
• Review chain in Manage Study → Test Chains

1. Check browser console:

• Look for errors about missing items
• API errors communicating with server

1. Clear browser cache:

• Old cached version may be stuck
• Hard refresh: Ctrl+F5 (Cmd+Shift+R on Mac)

Problem: Can't Edit Chain (Active Study)

Symptoms: Edit buttons disabled or greyed out

Explanation: This is intentional! Chains cannot be edited while study is active to ensure data integrity and reproducibility.

Solution:

1. Deactivate study (if no data collected yet):

• Go to My Research Studies
• Toggle study to inactive
• Edit chain
• Reactivate when ready

1. Create new chain (if data already collected):

• Leave original chain as-is for existing participants
• Create new chain with changes
• Start new recruitment with new chain

Problem: Study Showing as Inactive

Symptoms: Can't generate URLs, tests hidden

Solution:

1. Activate the study:

• Go to My Research Studies
• Find your study
• Toggle switch to "Active"

1. Check study hasn't expired:

• Look at expiration date
• Extend if needed in study settings

Data Issues

Problem: Missing Participant Data

Symptoms: Expected participant not showing in Browse Data

Solutions:

1. Check if participant completed:

• Participant may have started but not finished
• Look for "In Progress" status
• Check last activity timestamp

1. Verify correct study:

• May be looking at wrong study
• Check study name and token match

1. Check upload success:

• Ask participant if they saw "Upload complete" message
• Network issues can prevent upload

1. Look in analytics:

• Some participant data may show in analytics even if incomplete

Problem: Can't Download Data

Symptoms: Download button doesn't work, empty ZIP file

Solutions:

1. Check data exists:

• Browse Data should show participants
• No participants = no data to download

1. Try individual downloads:

• Instead of "Download All", try downloading one test
• Helps identify if specific test causing issue

1. Check browser download settings:

• Downloads may be blocked
• Check browser's download folder
• Try different browser

1. Wait if study just started:

• Data may still be processing
• Wait a few minutes and try again

Problem: Data Files Look Wrong

Symptoms: CSV files empty, corrupted, or unexpected format

Solutions:

1. Check file format:

• PEBL produces CSV files
• Open with Excel, R, Python, or text editor
• Verify file extension is .csv

1. Check encoding:

• Files should be UTF-8 encoded
• Some programs need encoding specified when opening

1. Look for README:

• Downloaded ZIP includes README explaining file structure
• Reference test-specific documentation

Participant Code Issues

Problem: Participant Gets New ID Every Time

Symptoms: Same participant appears as multiple different IDs

Solutions:

1. Use manual participant codes:

• Auto-generation uses browser fingerprinting
• Different devices/browsers = different IDs
• For critical studies, use manual codes

1. Instruct participants:

• Use same device and browser
• Don't clear browser data between sessions
• Don't use incognito/private mode

1. Use platform integration:

• Prolific, MTurk automatically provide stable IDs
• See Platform Integration

Problem: Participant Code Already in Use

Symptoms: Error about duplicate participant code

Solutions:

1. Choose different code:

• Each participant needs unique code per study
• Try adding suffix: SUBJ0012, SUBJ001retry

1. Check if participant already completed:

• May be trying to redo study
• Decide if you want to allow re-testing

Platform Integration Issues

Problem: Prolific Participants Not Redirecting

Symptoms: Participants complete study but don't return to Prolific

Solutions:

1. Check completion code configured:

• Completion page must have code format
• Redirect URL must include {COMPLETIONCODE}

1. Check redirect URL format:

• Should be: https://app.prolific.com/submissions/complete?cc={COMPLETIONCODE}
• Verify no typos

1. Test yourself:

• Use Prolific preview mode
• Complete chain and verify redirect works

Problem: MTurk Submission Not Counting

Symptoms: MTurk shows HIT incomplete even after participant finished

Solutions:

1. Check external submit URL:

• Must include {{assignmentId}} variable
• Verify format matches current MTurk requirements

1. Check completion code generated:

• MTurk typically requires completion code
• Verify code format configured

1. Contact MTurk support:

• MTurk's external submit system occasionally changes
• Check MTurk documentation for current format

Short URL Issues

Problem: Short URL Not Redirecting

Symptoms: 404 error or short URL shows error page

Solutions:

1. Verify short URL generated successfully:

• Check for "✓ Generated" message
• Try regenerating

1. Check server configuration:

• Short URLs require server rewrite rules
• Contact administrator if issue persists

1. Use full URL as fallback:

• Full URLs always work
• Short URL is optional convenience feature

Problem: Short URL Goes to Wrong Test

Symptoms: Short URL loads different test than expected

Solutions:

1. Regenerate short URL:

• Parameters may have been embedded when created
• Delete and create new short URL after changing parameters

1. Check which participant code used:

• Short URLs embed participant code if specified
• May have generated URL with wrong code entered

Storage and Account Issues

Problem: Storage Quota Exceeded

Symptoms: Can't upload new tests, error about storage limit

Solutions:

1. Download and delete old studies:

• Archive completed studies locally
• Delete from platform to free space

1. Clean up abandoned sessions:

• Delete incomplete participant sessions (carefully!)
• Focus on very old abandoned sessions

1. Upgrade subscription tier:

• Contact administrator about upgrading
• Higher tiers have more storage

Problem: Can't Create More Studies

Symptoms: Error about study limit reached

Solution:

1. Archive or delete old studies:

• Each tier has study limit
• Free: 1 active study
• Student: 5 active studies
• Researcher: 15 active studies

1. Deactivate instead of delete:

• Inactive studies don't count against limit
• Can reactivate if needed

1. Upgrade tier:

• Contact administrator about upgrading

Error Messages

"Authentication Required"

Meaning: Not logged in or session expired

Solution: Log in again, then retry action

"Access Denied" / "Permission Denied"

Meaning: Don't have permission for this action

Solutions:

• Verify you own the study
• Contact study owner for permissions
• Check if you're collaborator with correct access level

"Invalid Study Token"

Meaning: Study token doesn't exist or is malformed

Solutions:

• Check URL has correct token
• Verify study hasn't been deleted
• Try copying URL again from Manage Study page

"Chain Not Found"

Meaning: Chain ID doesn't exist

Solutions:

• Verify chain ID in URL is correct
• Check chain hasn't been deleted
• Try regenerating URL from Manage Study

"Missing Required Parameters"

Meaning: URL missing necessary parameters

Solutions:

• Chain URLs need both chain= and token= parameters
• Check entire URL copied correctly
• Regenerate URL from Manage Study

"Database Error"

Meaning: Server-side database issue

Solutions:

• Try again in a few minutes
• If persists, contact administrator
• May be temporary server maintenance

When to Contact Support

Contact your platform administrator if:

• Persistent errors that solutions above don't fix
• Data loss or missing critical data
• Account issues (can't log in, permissions wrong)
• Server errors (500 errors, database errors)
• Feature not working as documented
• Security concerns

Before contacting support, gather:

• Description of problem
• Error messages (exact text or screenshot)
• Browser and version used
• Steps to reproduce the problem
• Study token (if relevant)
• When problem started

Diagnostic Checklist

Use this checklist to diagnose issues:

Browser checks:

• [ ] Using modern browser (Chrome 90+, Firefox 88+, Safari 14+)?
• [ ] JavaScript enabled?
• [ ] Ad blockers disabled or site whitelisted?
• [ ] Tried incognito/private mode?
• [ ] Checked browser console (F12) for errors?

Study checks:

• [ ] Study is active (not inactive or expired)?
• [ ] URL includes all required parameters?
• [ ] Have permissions to perform action?
• [ ] Parameters saved successfully?

Network checks:

• [ ] Stable internet connection?
• [ ] Can access other websites normally?
• [ ] Behind firewall that might block uploads?

Data checks:

• [ ] Participant actually completed test?
• [ ] Looking at correct study?
• [ ] Data uploaded successfully (no console errors)?

Prevention Tips

Avoid problems before they start:

1. Test everything first:

• Complete study yourself before sharing with participants
• Try on multiple browsers
• Test with pilot participants

1. Keep URLs organized:

• Save URLs in spreadsheet
• Document which URL goes to which participant
• Use short URLs to reduce copy/paste errors

1. Monitor regularly:

• Check study analytics frequently
• Catch issues early when few participants affected
• Download data regularly as backup

1. Use clear instructions:

• Tell participants which browser to use
• Provide troubleshooting contact info
• Explain what to do if they encounter problems

1. Plan for contingencies:

• Have backup plan if technical issues arise
• Know how to contact administrator
• Keep records of study configuration

Related Topics

• Getting Started - Basic platform usage
• Configuring Test Parameters - Parameter issues
• Managing Data - Data access problems
• Creating Test Chains - Chain configuration
• Platform Integration - External platform issues

---

Still need help? Contact your platform administrator with details about your issue and any error messages you're seeing.

---

Related Topics

• Getting Started
• Managing Data
• Configuring Test Parameters
• Creating Test Chains