hristudio/TRIAL_START_DEBUG.md

Trial Start Debug Guide

❌ Problem: "I can't start the trial"

This guide will help you systematically debug why the trial start functionality isn't working.

---

🔍 Step 1: Verify System Setup

Database Connection

# Check if database is running
docker ps | grep postgres

# If not running, start it
bun run docker:up

# Check database schema is up to date
bun db:push

# Verify seed data exists
bun db:seed

Build Status

# Ensure project builds without errors
bun run build

# Should complete successfully with no TypeScript errors

---

🔍 Step 2: Browser-Based Testing

Access the Wizard Interface

1. Start dev server: bun dev
2. Open browser: http://localhost:3000
3. Login: sean@soconnor.dev / password123
4. Navigate: Studies → [First Study] → Trials → [First Trial] → Wizard Interface

Check Browser Console

Open Developer Tools (F12) and look for:

Expected Debug Messages (when clicking "Start Trial"):

[WizardInterface] Starting trial: <id> Current status: scheduled
[WizardControlPanel] Start Trial clicked

Error Messages to Look For:

• Network errors (red entries in Console)
• tRPC errors (search for "trpc" or "TRPC")
• Authentication errors (401/403 status codes)
• Database errors (check Network tab)

---

🔍 Step 3: Test Database Access

Quick API Test

Visit this URL in your browser while dev server is running:

http://localhost:3000/api/test-trial

Expected Response:

{
  "success": true,
  "message": "Database connection working",
  "trials": [...],
  "count": 4
}

If you get an error, the database connection is broken.

Check Specific Trial

If the above works, test with a specific trial ID:

http://localhost:3000/api/test-trial?id=<trial-id-from-above-response>

---

🔍 Step 4: Verify Trial Status

Requirements for Starting Trial

1. Trial must exist - Check API response has trials
2. Trial must be "scheduled" - Status should be "scheduled", not "in_progress" or "completed"
3. User must have permissions - Must be administrator, researcher, or wizard role
4. Experiment must have steps - Trial needs an experiment with defined steps

Check Trial Data

In browser console, after navigating to wizard interface:

// Check trial data
console.log("Current trial:", window.location.pathname);

// Check user session
fetch('/api/auth/session').then(r => r.json()).then(console.log);

---

🔍 Step 5: tRPC API Testing

Test tRPC Endpoint Directly

In browser console on the wizard page:

// This should work if you're on the wizard interface page
// Replace 'TRIAL_ID' with actual trial ID from URL
fetch('/api/trpc/trials.get?batch=1&input={"0":{"json":{"id":"TRIAL_ID"}}}')
  .then(r => r.json())
  .then(console.log);

Test Start Trial Endpoint

// Test the start trial mutation
fetch('/api/trpc/trials.start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "0": {
      "json": {
        "id": "TRIAL_ID_HERE"
      }
    }
  })
}).then(r => r.json()).then(console.log);

---

🔍 Step 6: Common Issues & Fixes

Issue: "Start Trial" Button Doesn't Respond

• Check browser console for JavaScript errors
• Verify the button isn't disabled
• Check if isStarting state is stuck on true

Issue: Network Error / API Not Found

• Check middleware isn't blocking tRPC routes
• Verify NextAuth session is valid
• Check if API routes are properly built

Issue: Permission Denied

• Check user role: must be administrator, researcher, or wizard
• Verify study membership if role-based access is enabled
• Check checkTrialAccess function in trials router

Issue: "Trial can only be started from scheduled status"

• Current trial status is not "scheduled"
• Find a trial with "scheduled" status or create one manually
• Check seed data created scheduled trials properly

Issue: Database Connection Error

• Database container not running
• Environment variables missing/incorrect
• Schema not pushed or out of date

---

🔧 Manual Debugging Steps

Create Test Trial

If no scheduled trials exist:

-- Connect to database and create a test trial
INSERT INTO trial (
  id, 
  experiment_id, 
  participant_id, 
  status, 
  session_number,
  scheduled_at,
  created_at,
  updated_at
) VALUES (
  gen_random_uuid(),
  'EXPERIMENT_ID_HERE',
  'PARTICIPANT_ID_HERE', 
  'scheduled',
  1,
  NOW(),
  NOW(),
  NOW()
);

Check User Permissions

-- Check user system roles
SELECT u.email, usr.role 
FROM users u 
LEFT JOIN user_system_roles usr ON u.id = usr.user_id 
WHERE u.email = 'sean@soconnor.dev';

-- Check study memberships
SELECT u.email, sm.role, s.name as study_name
FROM users u 
LEFT JOIN study_members sm ON u.id = sm.user_id
LEFT JOIN studies s ON sm.study_id = s.id
WHERE u.email = 'sean@soconnor.dev';

---

🚨 Emergency Fixes

Quick Reset

# Complete reset of database and seed data
bun run docker:down
bun run docker:up
bun db:push
bun db:seed

Bypass Authentication (Development Only)

In src/server/api/routers/trials.ts, temporarily comment out the permission check:

// await checkTrialAccess(db, userId, input.id, [
//   "owner",
//   "researcher", 
//   "wizard",
// ]);

---

📞 Getting Help

If none of the above steps resolve the issue:

1. Provide the following information:

   • Output of /api/test-trial
   • Browser console errors (screenshots)
   • Network tab showing failed requests
   • Current user session info
   • Trial ID you're trying to start

2. Include environment details:

   • Operating system
   • Node.js version (node --version)
   • Bun version (bun --version)
   • Docker status (docker ps)

3. Steps you've already tried from this guide

---

✅ Success Indicators

When trial start is working correctly, you should see:

1. Debug logs in console:

   [WizardInterface] Starting trial: abc123 Current status: scheduled
   [WizardControlPanel] Start Trial clicked
   [WizardInterface] Trial started successfully
   

2. UI changes:

   • "Start Trial" button disappears/disables
   • Toast notification: "Trial started successfully"
   • Trial status badge changes to "in progress"
   • Control buttons appear (Pause, Next, Complete, Abort)

3. Database changes:

   • Trial status changes from "scheduled" to "in_progress"
   • started_at timestamp is set
   • Trial event is logged with type "trial_started"

The trial start functionality is working when all three indicators occur successfully.