Troubleshooting Guide

This page provides a symptom-based index to help quickly identify and resolve integration issues. Use the tables below to find the right documentation for your problem.

Quick Diagnosis

flowchart TD
    A[Integration Issue] --> B{What type?}
    B -->|Data missing/wrong| C[Data Issue]
    B -->|Sync not running| D[Sync Issue]
    B -->|Auth/connection failed| E[Connection Issue]
    B -->|SSO not working| F[SSO Issue]

    C --> C1[Check File Logs]
    C --> C2[Verify Vendor Response]

    D --> D1[Check Queue Workers]
    D --> D2[Check Scheduler]

    E --> E1[Check Credentials]
    E --> E2[Check Certificates]

    F --> F1[Check SAML Config]
    F --> F2[Check User Mapping]

By Symptom

Data Issues

Symptom	Possible Cause	Documentation
Data not updating	Sync not running, Vendor not sending	[Nightly Sync](nightly-sync/
Missing accounts	Account not linked, Vendor filter	[File Integrations](../../components/file-integrations/
Wrong values	Vendor data incorrect, Parsing bug	[Data Issues Guide](data-issues/
Duplicate records	Mapping conflict, Re-import	[Data Issues Guide](data-issues/
Stale prices	Morningstar sync issue	[Morningstar](../../components/morningstar/
Security not matched	Missing from Security Master	[Morningstar](../../components/morningstar/

Sync Issues

Symptom	Possible Cause	Documentation
Sync not running	Scheduler down, Queue workers stopped	[Nightly Sync](nightly-sync/
Partial sync	Some jobs failed, Rate limiting	[Nightly Sync](nightly-sync/
Slow sync	Large data volume, API latency	[Nightly Sync](nightly-sync/
Jobs stuck in queue	Worker crash, Database lock	[Nightly Sync](nightly-sync/

Connection Issues

Symptom	Possible Cause	Documentation
OAuth expired	Token refresh failed	[API Integrations](../../components/api-integrations/
API 401 error	Credentials invalid	[API Integrations](../../components/api-integrations/
API 429 error	Rate limited	[API Integrations](../../components/api-integrations/
SFTP connection failed	Credentials rotated, IP not whitelisted	[Vendor Management](vendor-management/
Certificate error	Certificate expired	[Vendor Management](vendor-management/
Files not arriving	Vendor SFTP issue	[Collector](../../components/collector/

SSO Issues

Symptom	Possible Cause	Documentation
SSO login failed	User not found, Invalid signature	[SSO](../../components/sso/
Assertion expired	Clock skew, Stale request	[SSO](../../components/sso/
Wrong user logged in	Identifier mismatch	[SSO](../../components/sso/
Contextual SSO not working	Household mapping missing	[SSO](../../components/sso/

Investigation Tools

Tool	Purpose	Access
Admin Center	View integrations, logs, user data	`admin.rightcapital.com`
AWS Console (S3)	Check file logs, LATEST files	Via Microsoft SSO
Crypt Tool	Decrypt account IDs from URLs	Admin Center
Queue Monitor	Check job status	Internal dashboard

Common Commands

# Check sync status for a mapping
php artisan integration:status --mapping-id=12345

# Trigger manual sync for one mapping
php artisan integration:sync --mapping-id=12345

# Sync all mappings for a vendor
php artisan integration:sync --vendor=schwab

# Check Collector status
# (run in Collector service)
./collector status --vendor=schwab

File Log Locations

Log Type	S3 Path
API request/response	`rightcapital-prd/logs/integration/{VENDOR}/{ADVISOR_ID}/{REFERENCE}`
Collector logs	`rightcapital-prd/integrations/{VENDOR}/logs/`

Escalation Path

Check obvious issues first - Is sync running? Are files present?
Review file logs - Check Vendor response data
Check timestamps - Match issue timing with logs
Document findings - Even if no code change needed
Escalate if needed - Create DEV ticket with findings

Data Issues Guide - Detailed investigation process
Nightly Sync - Sync scheduling and monitoring
Vendor Management - Vendor communication