GP3MixMedia TrailMix - Troubleshooting Guide

This guide helps you solve common issues you might encounter while using the GP3MixMedia TrailMix platform.

Table of Contents

1. Login & Access Issues
2. Data Not Appearing
3. File Upload Problems
4. Export & Download Issues
5. Deduplication Issues
6. Email & Alert Problems
7. Performance & Speed Issues
8. Data Quality Issues
9. Permission Errors
10. Browser & Display Issues

Login & Access Issues

Can't Log In

Google Workspace login issues:

1. Make sure you're selecting your work email, not personal email
2. Verify your domain is authorized to use the platform
3. Try logging out of all Google accounts and back in to just your work account
4. Clear browser cookies and try again
5. Contact your admin if issue persists

Can't See Any Campaigns After Login

Possible causes:

1. You haven't been granted access to any campaigns yet
2. All your campaigns were archived or deleted
3. Your account hasn't been fully set up

Solutions:

• Contact your admin to grant you access to specific campaigns
• Provide the campaign names you need access to
• Verify your email was spelled correctly when your account was created

"Session Expired" Message

This happens when:

• You've been inactive for an extended period
• Your login session timed out

Solution:

• Simply log in again
• Your work is auto-saved, so you shouldn't lose data
• Consider enabling "Remember me" if available

Data Not Appearing

Matrix Shows No Data

Check these:

1. Filters: Make sure filters aren't excluding all data
   • Try clicking "Reset Filters" or "Clear All"
   • Check date range isn't too narrow
2. Week Mode: Switch between Booked/Projected/All
3. Campaign Status: Ensure campaign is Active, not Paused
4. Ingestion Status: Check if data collection is configured and running

Steps to diagnose:

• Go to Input Hub → Ingestion tab
• Check "Recent Runs" to see if data is being collected
• Verify keywords and DMAs are configured
• Try manually triggering a feed with "Run Now"

Recent Data Missing

If data was there before but disappeared:

1. Check if a deduplication process removed it
2. Verify date range filter includes recent dates
3. Check exceptions tab for errors
4. Look at ingestion runs to see if recent runs failed
5. Contact your admin - data may have been archived

If new data isn't showing up:

• Ingestion runs on a schedule (not instant)
• FCC data: Updates every 6 hours (default)
• AdImpact: Updates hourly (default)
• Meta Ads Library: Daily
• Google Political Ads: Daily
• Manual uploads: Must click "Process" after upload
• Check if ingestion is paused (admins can pause/resume via Ingestion Control)

Uploaded File Not Showing in Matrix

Common causes:

1. File status is "Uploaded" not "Processed"
   • Solution: Click the "Process" button next to the file
2. Processing failed with errors
   • Solution: Click the file to view error details
3. Wrong file type was selected
   • Solution: Delete and re-upload with correct type
4. File format doesn't match expected structure
   • Solution: Check file template or contact support

Analytics Shows $0 Spend

Possible reasons:

1. No data has been ingested yet
2. All data is in future weeks (use "Projected" week mode)
3. Filters are too restrictive
4. Campaign just created and needs initial data load

Solutions:

• Try changing Week Mode to "All"
• Reset all filters
• Check Matrix to see if any data exists
• Wait for initial ingestion run to complete

File Upload Problems

Upload Button Not Working

Try these steps:

1. Refresh the page and try again
2. Check file size - very large files (>100MB) may have issues
3. Verify file type is supported (CSV, XLSX, PDF)
4. Try a different browser
5. Check your internet connection

"Upload Failed" Error

Common causes:

1. File too large: Compress or split the file
2. Network interruption: Try uploading again
3. File corrupted: Open file locally to verify it's not corrupted
4. Unsupported format: Ensure file extension matches content

Solutions:

• For large files, split into smaller chunks
• Use wired connection instead of WiFi if possible
• Save file in compatible format (CSV or XLSX)

Processing Stuck at "Processing..."

If processing doesn't complete:

1. Wait 5-10 minutes - large files take time
2. Refresh the page to see updated status
3. If still stuck after 15 minutes, it likely failed
4. Check for error status after refresh
5. Contact admin to check server logs

"Parse Error" After Processing

This means the system couldn't extract data from your file.

Common issues:

1. Wrong file type selected during upload
   • Solution: Delete and re-upload with correct type
2. Unexpected format - columns in wrong order or missing
   • Solution: Match the expected template format
3. Corrupt file - file damaged or incomplete
   • Solution: Re-export from source and upload again
4. Empty file - no data rows present
   • Solution: Verify file contains data

To get details:

• Click on the file name in the uploads list
• View the error message for specifics
• Check which rows or columns caused issues

Export & Download Issues

Export Stays "Generating..." Forever

For CSV/XLSX exports:

• Large campaigns can take 30-60 seconds
• Don't close the browser tab while exporting
• If it exceeds 2 minutes, refresh and try again
• Try adding filters to export less data

For PDF exports:

• PDFs with charts can take 60-90 seconds
• Very complex dashboards may timeout
• Try simplifying the view before export
• Reduce date range to export smaller timeframe

Downloaded File Won't Open

CSV files:

• Make sure you're opening with Excel or Google Sheets
• Right-click file → Open With → Excel
• Some CSV files open in text editors by default

XLSX files:

• Requires Microsoft Excel or compatible program
• Try Google Sheets if Excel isn't available
• Verify download completed (check file size isn't 0 bytes)

PDF files:

• Ensure you have a PDF reader (Adobe, Preview, etc.)
• Re-download if file appears corrupted
• Try a different browser

Downloaded Data Looks Wrong

Check these:

1. Filters: Export includes your current filters
2. Week Mode: Booked vs Projected affects what's exported
3. Date Range: Verify range includes the data you want
4. Decimal Places: Spend may show more precision than dashboard

To fix:

• Reset all filters before export
• Switch to "All" week mode for complete data
• Adjust date range to include all relevant weeks
• Re-export after making changes

Deduplication Issues

Can't See Differences Between Duplicates

If records look identical:

1. Scroll horizontally to see all columns
2. Differences might be in notes, source, or metadata fields
3. Dates might differ by one day
4. Spend might differ by cents (e.g., $1,000.00 vs $1,000.50)

Use the comparison view:

• Platform highlights differences in red/green
• Scroll through all fields carefully
• Check source column to see where each came from

Accidentally Merged Wrong Records

Good news - you can undo!

1. Go to Deduplication
2. Find the group you just resolved
3. Click "History" or "View Resolution"
4. Click "Undo" button
5. Original records are restored
6. Group returns to "Open" status

Note: Only recent merges can be undone. After a certain period, undo may not be available.

Dedupe Group Won't Combine

If "Combine" button doesn't work:

1. Verify you have Analyst or Admin role (Viewers can't merge)
2. Check that all required fields are selected
3. Ensure at least 2 records are selected to merge
4. Try refreshing the page
5. Contact admin if permission error appears

Same Records Keep Appearing as Duplicates

If you marked them separate but they keep grouping:

1. System may be detecting new similarities
2. New data from another source might be matching
3. Resolution status might not have saved

Solutions:

• Add a note explaining why they're separate
• Verify "Skip" was saved (should show "Skipped" status)
• Contact admin to adjust deduplication rules if this is common

Email & Alert Problems

Not Receiving Alert Emails

Check these first:

1. Spam folder - most common issue
2. Email address - verify it's spelled correctly in settings
3. Threshold - make sure actual changes exceed your threshold
4. Delivery status - check Output Hub → Email tab to see if it was sent

In Output Hub → Email tab:

• Green checkmark = delivered successfully
• Red X = bounced or failed
• Yellow = pending delivery

Solutions:

1. Add sender to your email safe list / contacts
2. Whitelist gp3mixmedia.com domain
3. Check with IT about email filtering rules
4. Try a different email address

Email Alerts Triggering Too Often

To reduce frequency:

1. Go to Settings → Alerts
2. Increase the threshold amount
3. Change frequency from "Immediate" to "Daily Digest"
4. Adjust which events trigger alerts
5. Save changes

Report Email Looks Broken

If formatting is off:

1. Check which email client you're using
   • Some clients (Outlook, Gmail) render differently
2. Click "View in Browser" link in email
3. Download PDF attachment instead
4. Report rendering issues to admin with email client details

"Send Test Email" Button Doesn't Work

Requires Admin or specific email permissions:

1. Verify you have permission to send emails
2. Check your role (Viewer cannot send)
3. Ensure email settings are configured
4. Try refreshing the page
5. Check browser console for errors (F12)

Performance & Speed Issues

Platform Loading Slowly

Quick fixes:

1. Refresh the page (Ctrl+R or Cmd+R)
2. Close other browser tabs to free memory
3. Clear browser cache and cookies
4. Try a different browser (Chrome, Firefox, Edge)
5. Check your internet connection speed

For large campaigns:

• Use filters to view smaller data sets
• Export data rather than viewing all rows
• Close and re-open the campaign
• Ask admin about campaign data archiving

Matrix Takes Forever to Load

Large campaigns with thousands of rows load slowly:

Solutions:

1. Use filters immediately:
   • Filter by date range first
   • Select specific markets
   • Choose one media type
2. Change week mode to reduce rows:
   • "Next Week" shows least data
   • "Booked" fewer than "All"
3. Export instead of viewing:
   • Download data to analyze locally
4. Ask admin about archiving:
   • Move old completed weeks to archive

Exports Timing Out

For very large exports:

1. Use date range filters to export in chunks
2. Export by market (one DMA at a time)
3. Export by media type separately
4. Try during off-peak hours
5. Contact admin about server resources

Page Freezes or Crashes

If browser becomes unresponsive:

1. Wait 30 seconds - it may be processing
2. Close tab and re-open (work is usually auto-saved)
3. Reduce browser memory usage:
   • Close unused tabs
   • Restart browser
   • Disable browser extensions
4. Try a different browser
5. Report to admin with details about what you were doing

Data Quality Issues

Seeing Duplicate Records That Aren't Flagged

The system tries to catch duplicates automatically but isn't perfect:

What to do:

1. Note the record IDs or details
2. Contact your team lead or admin
3. Explain why you believe they're duplicates
4. Admin can manually group them for resolution

Why it might happen:

• Very different dates or amounts
• Different station names for same station
• Different sources at different times
• Thresholds set to avoid false positives

Station Names Look Wrong or Inconsistent

Common issues:

• "WABC-TV" vs "WABC" vs "ABC New York"
• "ESPN" vs "ESPN New York"

This happens because:

• Different sources use different naming
• Deduplication should merge these over time

Solutions:

1. Report inconsistencies to admin
2. Admin can configure station name normalization
3. Use filters to group similar stations
4. Note standardized names in your exports

GRP or Impression Numbers Seem Wrong

Check these:

1. Source: Different sources calculate differently
2. Market size: Small DMAs have different scales
3. Daypart: Prime time vs overnight affects numbers
4. Week vs day: Make sure you're looking at weekly totals

If truly wrong:

1. Click the cell to edit (if you're an Analyst)
2. Enter correct value
3. Add note explaining the correction
4. Flag as exception if systematic issue

Missing Station Exceptions

When stations aren't identified:

Common causes:

• Station not in database yet
• Non-standard station name in source data
• National/digital buys without specific stations
• Data extraction didn't capture station field

To resolve:

1. Go to Exceptions tab
2. Find "Missing Station" exceptions
3. Click to open exception
4. Assign correct station from dropdown
5. Mark as resolved

Permission Errors

"You Don't Have Permission" Message

This means your role doesn't allow that action:

Common scenarios:

1. Viewers trying to edit data → Need Analyst role
2. Analysts trying to send emails → Need Admin role
3. Anyone trying to create campaigns → Need Admin role

Solutions:

1. Check what role you have (profile menu, top right)
2. Request role change from admin if needed
3. Ask someone with appropriate permissions to help
4. Review what each role can do in User Guide

Can't Access Certain Campaigns

User access is per-campaign:

Why this happens:

1. You haven't been granted access to that campaign
2. Campaign was recently created and access not yet configured
3. Your access was removed
4. Campaign was archived

Solution:

• Contact admin with:
  • Campaign name
  • Your email address
  • What role you need (Viewer, Analyst)

"Session Expired" When Trying to Save

Your login session timed out:

To avoid losing work:

1. Open new tab and log in again
2. Return to original tab
3. Copy any unsaved changes
4. Refresh the page
5. Re-enter your changes

Prevention:

• Save frequently
• Keep platform open in a tab (activity resets timer)
• Enable "Remember me" if available

Browser & Display Issues

Charts or Graphs Not Showing

Try these fixes:

1. Refresh the page (Ctrl+R)
2. Clear browser cache
3. Disable ad blockers or script blockers
4. Try a different browser
5. Check if JavaScript is enabled

If only charts are broken:

• Platform requires JavaScript to be enabled
• Some security software blocks chart libraries
• Try on a different network

Layout Looks Broken or Overlapping

Responsive design issues:

Quick fixes:

1. Zoom browser to 100% (Ctrl+0 or Cmd+0)
2. Try full-screen mode (F11)
3. Use larger monitor or window size
4. Clear browser cache
5. Update browser to latest version

Minimum requirements:

• Screen width: 1280px recommended
• Modern browser (Chrome, Firefox, Edge, Safari)
• JavaScript enabled

Can't Scroll Horizontally in Matrix

The matrix has many columns:

Tips:

1. Click and drag with mouse in matrix area
2. Use horizontal scroll bar at bottom
3. Use Shift + scroll wheel on mouse
4. Use trackpad two-finger swipe
5. Tab through cells with keyboard

Buttons Don't Respond to Clicks

If UI elements seem frozen:

Try:

1. Wait 10 seconds - page may still be loading
2. Refresh the page
3. Clear browser cache and cookies
4. Disable browser extensions
5. Try incognito/private mode
6. Use different browser

Still Having Issues?

Steps for Getting Help

1. Document the problem:

   • What were you trying to do?
   • What happened instead?
   • Any error messages?
   • What have you tried already?

2. Take screenshots if possible

3. Note details:

   • Campaign name
   • Your role
   • Browser and version
   • Time the issue occurred

4. Contact:

   • Your team lead or analyst colleagues
   • Your organization's admin
   • Technical support (if available)

Information to Provide

When reporting issues, include:

• User email: Your login email
• Campaign: Which campaign you were working on
• Action: What you were trying to do
• Error: Exact error message or behavior
• Browser: Chrome, Firefox, Safari, Edge (and version)
• Time: When the issue occurred
• Screenshot: If applicable

Preventing Common Issues

Best Practices

1. Save frequently: Don't make many changes without saving
2. Use filters: Makes large datasets manageable and faster
3. Export backups: Keep local copies of important data
4. Check sources: Verify data source before making assumptions
5. Add notes: Document unusual entries for future reference
6. Review duplicates regularly: Don't let them pile up
7. Monitor exceptions: Address data quality issues quickly
8. Test alerts: Send test emails to verify delivery
9. Use consistent browser: Stick to one tested browser
10. Keep browser updated: Use latest version

Maintenance Tips

Weekly:

• Clear browser cache
• Review and resolve dedupe groups
• Check for exceptions
• Verify email alerts are working

Monthly:

• Export backup of campaign data
• Review user access (Admins)
• Check ingestion configurations (Admins)
• Archive old completed data (Admins)

Additional Resources

• User Guide - Complete feature documentation
• Getting Started - Quick start guide
• FAQ - Common questions
• Glossary - Term definitions
• Ingestion Control Guide - Manage data collection, pause/resume, rate limiting
• Feed Configuration Guide - Configure data feeds (Meta Ads, FCC, AdImpact, etc.)
• Developer Quick Reference - Environment variables, crons, setup guide

Developer Troubleshooting

Build Fails with "Cannot access 'X' before initialization"

This is a circular dependency (temporal dead zone) error. API route files must use dynamic imports for service/worker modules:

// WRONG — causes TDZ error during build
import { someService } from '@/lib/services/some-service';

// RIGHT — dynamic import breaks the circular chain
async function getSomeService() {
  const { someService } = await import('@/lib/services/some-service');
  return someService;
}

Prisma Client Missing or Out of Date

Run npx prisma generate after pulling new code or changing the schema. If tests still fail, try npx prisma migrate deploy to apply any pending migrations.

Meta Feed Not Running

1. Check that META_ADS_API_TOKEN is set (not expired — tokens last 60 days)
2. Verify the feed is enabled in Campaign Settings > Feeds
3. Check /ingestion/feeds for error details
4. If rate limited, increase META_ADS_INTER_REQUEST_DELAY_MS

Gmail Polling Not Starting

Both REP_LABEL_ID and NEWSLETTER_LABEL_ID must be set to valid Gmail Label IDs (not label names). Use the label discovery tool:

npx tsx src/workers/mailbox/label-utils.ts

Database Connection Issues on Fly.io

• The app should connect via ProxySQL on port 6033, not MySQL directly on 3306
• Check DATABASE_URL format: mysql://USER:[email protected]:6033/gp3_mixmedia
• DNS caching issue: UV_DNS_TTL=30 is set in fly.toml to handle DB machine restarts

Worker Process Stuck

• Feed locks expire after 45 minutes (configurable via INGESTION_FEED_LOCK_TTL_SECONDS)
• Check the dead letter queue at /admin/dlq for persistent failures
• Restart the ingest process: fly machines restart --app gp3mixmedia-web --process ingest

Last Updated: March 2026