Troubleshooting Guide

Solutions to common AI Verification Service issues

Quick Diagnostics

Before diving into specific issues, perform these quick checks to identify common problems:

Basic Health Check

  1. Check service status at https://ai.copyrightchains.com/api/v1/health
  2. Verify your SempreID session is active in Dashboard
  3. Confirm you have administrator privileges
  4. Check browser console for JavaScript errors
  5. Verify network connectivity

Common Issues and Solutions

Issue: Verification Timeout

Symptoms: Verification stays in "processing" state for more than 2 minutes, or times out with error.

Possible Causes:

  • Large file size requiring extended processing
  • AI provider experiencing high latency
  • Network connectivity issues
  • Service queue overload

Solutions:

  1. Check service health: Visit /api/v1/health to see provider status
  2. Wait and retry: Give it 5 minutes, then retry verification
  3. Reduce file size: Compress audio files if very large (above 50MB)
  4. Try during off-peak hours: Early morning or late evening may have less queue
  5. Contact support: If persists after multiple attempts

Issue: Report Not Generated

Symptoms: Verification shows "completed" but no report is displayed.

Possible Causes:

  • Database write failure
  • Report formatting error
  • Session expired during processing
  • Browser cache issue

Solutions:

  1. Refresh page: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
  2. Check via API: Use GET /api/v1/report/:verificationId directly
  3. Re-authenticate: Log out and log back in to Dashboard
  4. Clear browser cache: Clear cookies and site data for Dashboard
  5. Retry verification: Submit new verification if report truly missing

Issue: Authentication Errors

Symptoms: "Authentication required" or "Insufficient permissions" errors when accessing service.

Possible Causes:

  • SempreID session expired
  • Not logged into Dashboard
  • Administrator privileges revoked
  • Cookie settings blocking session

Solutions:

  1. Verify Dashboard login: Ensure you're logged into Dashboard first
  2. Check admin status: Confirm your SempreID has admin privileges
  3. Enable cookies: Allow cookies from copyrightchains.com domain
  4. Try incognito mode: Rule out browser extension interference
  5. Contact administrator: Request admin privileges if missing

Issue: Low Confidence Scores

Symptoms: All verification types return very low confidence scores or uncertain results.

Possible Causes:

  • Insufficient content provided for analysis
  • Poor quality audio or corrupted files
  • Unusual or experimental music style
  • Missing metadata or incomplete submission

Solutions:

  1. Add more content: Provide lyrics, scores, or additional files
  2. Check file quality: Ensure audio is clear and not corrupted
  3. Improve metadata: Add accurate duration, format, and technical details
  4. Use higher quality audio: 320kbps MP3 or lossless formats preferred
  5. Manual review: Proceed with human judgment when AI uncertain

Issue: Provider Failures

Symptoms: Report shows some providers failed or returned errors.

Possible Causes:

  • Specific AI provider experiencing outage
  • Provider rate limit exceeded
  • API key expired or invalid
  • Content format not supported by provider

Solutions:

  1. Check health endpoint: See which providers are operational
  2. Review partial results: Use available provider data for decision
  3. Wait and retry: Provider may recover shortly
  4. Accept partial analysis: Multiple providers provide redundancy
  5. Report to support: If specific provider consistently fails

Issue: File Upload Errors

Symptoms: Files fail to upload or verification rejected due to file problems.

Possible Causes:

  • File exceeds maximum size limit
  • Unsupported file format
  • Corrupted or damaged file
  • Special characters in filename

Solutions:

  1. Check file sizes: Audio max 100MB, documents max 10MB
  2. Convert format: Use MP3, WAV, FLAC for audio; PDF for documents
  3. Test file integrity: Open file to verify it's not corrupted
  4. Rename file: Remove special characters from filename
  5. Compress if needed: Reduce file size while maintaining quality

Issue: Inconsistent Results

Symptoms: Running same verification multiple times produces different results.

Possible Causes:

  • Different providers used between runs
  • AI models updated between verifications
  • Database content changed (new registrations added)
  • Random variation in AI analysis

Solutions:

  1. Compare detailed findings: Check if actual evidence differs
  2. Look for consensus: Multiple runs showing similar patterns
  3. Use most recent: Latest run reflects current database state
  4. Average scores: Consider average of multiple runs for borderline cases
  5. Document variations: Note inconsistencies in decision reasoning

Issue: Queue Stuck

Symptoms: Verification stays in "queued" state for extended period without processing.

Possible Causes:

  • Queue processing paused or stopped
  • All workers busy with long-running verifications
  • Database connection lost
  • Redis queue failure

Solutions:

  1. Check queue metrics: Visit /api/v1/metrics for queue status
  2. Wait for current jobs: May clear once active verifications complete
  3. Cancel and resubmit: If stuck more than 10 minutes
  4. Contact support: If queue appears frozen
  5. Try off-peak hours: Less queue congestion

Issue: Dashboard Integration Broken

Symptoms: "Run AI Verification" button not appearing or not working in Dashboard.

Possible Causes:

  • Dashboard not updated to latest version
  • JavaScript error preventing button render
  • Admin permissions not properly detected
  • Service URL misconfigured

Solutions:

  1. Check browser console: Look for JavaScript errors
  2. Hard refresh Dashboard: Clear cache and reload
  3. Verify admin status: Confirm privileges in Dashboard settings
  4. Use API directly: Call verification endpoints via API as workaround
  5. Report bug: Contact support with error details

Issue: False Positives/Negatives

Symptoms: AI incorrectly identifies legitimate content as problematic, or misses actual issues.

Possible Causes:

  • Edge case not covered in training data
  • Unusual music style or format
  • Coincidental similarity to existing work
  • AI model limitations

Solutions:

  1. Review detailed findings: Check if AI reasoning makes sense
  2. Use human judgment: Override AI when clearly wrong
  3. Request additional evidence: Get more info from applicant
  4. Document override: Note why you disagreed with AI
  5. Report to support: Help improve AI with feedback

Error Messages Reference

Common Error Messages

AUTH_REQUIRED: "Authentication required"

  • You're not logged into Dashboard
  • Session expired, log in again

INSUFFICIENT_PERMISSIONS: "Administrator access required"

  • Your account doesn't have admin privileges
  • Contact administrator to grant permissions

INVALID_REQUEST: "Invalid request format"

  • Missing required fields in API call
  • Check API documentation for correct format

FILE_TOO_LARGE: "File exceeds size limit"

  • Audio file over 100MB limit
  • Compress file or use lower bitrate

RATE_LIMIT_EXCEEDED: "Too many requests"

  • Exceeded 100 requests per hour
  • Wait before making more requests

PROVIDER_ERROR: "AI provider failed"

  • Specific provider experiencing issues
  • Check health endpoint for provider status
  • Retry or accept partial results

TIMEOUT: "Verification timed out"

  • Processing took longer than maximum allowed
  • Retry verification
  • Try with smaller files if issue persists

NOT_FOUND: "Verification not found"

  • Invalid verification ID
  • Verification was deleted
  • Check ID and retry

Performance Issues

Slow Verification Processing

If verifications consistently take longer than expected:

  1. Check file sizes - smaller files process faster
  2. Review queue metrics - high backlog increases wait time
  3. Try during off-peak hours for faster processing
  4. Ensure files are in optimal formats (MP3 over WAV)
  5. Contact support if consistently over 2 minutes

Dashboard Slow to Load Reports

If reports take long time to display:

  1. Check network connection speed
  2. Clear browser cache and cookies
  3. Disable browser extensions temporarily
  4. Try different browser
  5. Use API directly if Dashboard consistently slow

Getting Additional Help

Before Contacting Support

Gather this information to expedite support:

  • Verification ID: UUID of problematic verification
  • Timestamp: When issue occurred
  • Error Messages: Exact error text or codes
  • Browser Details: Browser type and version
  • Screenshots: Visual evidence of issue
  • Console Logs: JavaScript errors from browser console
  • Steps to Reproduce: What you did that caused issue

Contact Channels

  • Dashboard Support: Use "Help" button in Dashboard
  • Email Support: [email protected]
  • Service Health: https://ai.copyrightchains.com/api/v1/health
  • Documentation: Review other help pages for solutions

Priority Support Issues

These issues receive expedited support:

  • Service completely unavailable
  • Multiple administrators experiencing same problem
  • Data loss or missing reports
  • Security or privacy concerns
  • Critical registration deadlines at risk

Prevention Tips

Avoid Common Problems

  • Always validate files before submission
  • Check service health before batch operations
  • Keep browser and Dashboard up to date
  • Document issues when they occur
  • Maintain active SempreID session

Related Topics

Using the Service

Proper workflow and procedures

API Integration

Technical API documentation

Best Practices

Guidelines to avoid issues

FAQ

Frequently asked questions