Troubleshooting

Common issues, error messages, and resolution procedures

Authentication Issues

Invalid Credentials Error

Message: 401 Unauthorized — Invalid credentials

Cause: Email or password is incorrect, or account is locked.

Resolution:

1. Verify email address is correct (case-sensitive)
2. Check for Caps Lock
3. If locked, wait 15 minutes or contact administrator
4. Use demo credentials: analyst@rayray.demo / Analyst123!

Token Expired

Message: 401 Unauthorized — Token has expired

Cause: JWT access token expired (default: 30 minutes).

Resolution:

1. Frontend automatically refreshes tokens via refresh token
2. If refresh fails, log out and log back in
3. Check system clock synchronization (NTP)

MFA Verification Failed

Message: 401 Unauthorized — Invalid MFA code

Cause: TOTP code is incorrect or expired.

Resolution:

1. Ensure authenticator app time is synchronized
2. Enter code quickly (30-second window)
3. Do not reuse codes
4. If persistent, reset MFA via Settings → Security

Document Upload Issues

File Too Large

Message: 413 Payload Too Large

Cause: File exceeds maximum size (50MB).

Resolution:

1. Split large PDFs into smaller documents
2. Compress images within documents
3. For Excel, remove unused sheets/rows
4. Contact admin for increased limit

Unsupported File Type

Message: 400 Bad Request — Unsupported file type

Cause: File extension not in allowed list.

Resolution:

1. Convert to supported format: PDF, XLSX, XLS, CSV
2. Ensure file extension matches content
3. Do not rename file extensions manually

Corrupted File

Message: 422 Unprocessable Entity — Unable to extract content

Cause: File structure is damaged or malformed.

Resolution:

1. Re-export from source application
2. Try "Save As" to create fresh copy
3. Repair tools: Adobe Acrobat (PDF), Excel "Open and Repair"

Extraction Issues

Extraction Timeout

Message: 504 Gateway Timeout — Extraction timed out

Cause: Document too complex or LLM API slow.

Resolution:

1. Retry extraction (may be transient)
2. Split document into smaller sections
3. Check Claude API status: status.anthropic.com
4. Contact support if persistent

Low Confidence Extractions

Message: Warning: 5 extractions below confidence threshold

Cause: AI uncertain about extracted values.

Resolution:

1. Review low-confidence extractions carefully
2. Click extraction to see source location
3. Correct values if necessary
4. If source is ambiguous, request clarification

Missing Attributes

Message: Warning: 3 attributes not found

Cause: Document does not contain expected attributes.

Resolution:

1. Verify document is appropriate for scoring profile
2. Check if attribute uses different naming/units
3. Manually enter values if known from other sources
4. Mark as "Not Available" if genuinely absent

Comparison Issues

Insufficient Documents

Message: 400 Bad Request — Minimum 2 documents required

Cause: Comparison requires at least 2 documents.

Resolution: Upload and extract at least 2 documents before creating comparison.

Profile Weight Error

Message: 400 Bad Request — Weights must sum to 1.0

Cause: Scoring profile weights are misconfigured.

Resolution:

1. Edit scoring profile
2. Adjust weights to sum to exactly 1.0
3. Example: 0.25 + 0.25 + 0.30 + 0.20 = 1.00

Export Issues

PPTX Generation Failed

Message: 500 Internal Server Error — PPTX generation failed

Cause: python-pptx library not installed or corrupted.

Resolution:

# Check installation
pip show python-pptx

# Reinstall if missing
pip install python-pptx

PDF Generation Failed

Message: 500 Internal Server Error — PDF generation failed

Cause: reportlab library not installed or corrupted.

Resolution:

# Check installation
pip show reportlab

# Reinstall if missing
pip install reportlab

Audit System Issues

Hash Chain Verification Failed

Message: Verification failed at event evt_xyz123

Cause: Audit log integrity compromised (rare, serious).

Resolution:

1. This indicates potential tampering — escalate immediately
2. Preserve all logs for investigation
3. Contact ISSO/ISSM
4. Document timeline of events

Audit Query Timeout

Message: 504 Gateway Timeout — Query timed out

Cause: Querying too many events without proper filters.

Resolution:

1. Add date range filters
2. Filter by event type
3. Use pagination (limit/offset)
4. Contact admin for large data exports

Permission Errors

Insufficient Role

Message: 403 Forbidden — Insufficient permissions

Cause: User role does not have required permission.

Resolution:

Performance Issues

Slow Document Loading

Symptoms: Document viewer takes >10 seconds to load.

Possible Causes:

• Large file size (>20MB)
• Network latency
• Server under load

Resolution:

1. Check network connection
2. Try during off-peak hours
3. Split large documents
4. Contact admin if persistent

Extraction Queue Backlog

Symptoms: Extractions pending for >5 minutes.

Cause: High system load or LLM API rate limits.

Resolution:

1. Wait for queue to process
2. Avoid submitting multiple extractions simultaneously
3. Contact admin if backlog persists >30 minutes

Diagnostic Commands

Check API Health

curl -s http://localhost:8000/health | jq

Check Database Connection

# From apps/api directory
python -c "from app.database import engine; print(engine.url)"

Verify Claude API Key

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Check Audit Log Integrity

curl -s http://localhost:8000/api/audit/verify \
  -H "Authorization: Bearer $TOKEN" | jq

Error Code Reference

Support Escalation

Related

• API Reference — Error codes and responses
• Audit System — Log verification
• Authentication — Auth troubleshooting