Skip to main content

Appendix G — Troubleshooting

Authentication Issues​

"Invalid credentials" on login​

  • Verify your email and password are correct.
  • Check if your account has been suspended (ask your admin).
  • If you recently changed passwords, ensure you are using the new password.
  • Try resetting your password via "Forgot Password" on the login page.

"Your session has expired"​

Sessions expire after the configured idle timeout (default 60 minutes). Log in again. If this occurs frequently, ask your admin to increase the session timeout in System Configuration.

Stuck on "Change Password" screen​

If you are permanently stuck on the change password screen, your must_change_password flag is set. Complete the password change form --- the new password must meet the minimum complexity requirements. If the screen reappears after changing, clear your browser cookies and log in again.

Cohort Building Issues​

Cohort generation fails with "Schema not found"​

The daimon schema configured in the data source does not exist in the database. Ask your admin to verify the data source schema names match the actual PostgreSQL schema names. Schema names are case-sensitive in PostgreSQL.

Cohort count is 0 (empty cohort)​

Common causes:

  1. Concept set resolves to 0 IDs --- the concept set uses concepts not present in the loaded vocabulary. Click "Preview" on the concept set to check resolved IDs.
  2. Time window too restrictive --- the index event window or observation window excludes all patients. Try relaxing the date range.
  3. CDM schema is empty --- the data source points to a schema with no patient data. Check the Overview tab in Data Explorer for record counts.
  4. Incorrect schema in daimon --- the CDM daimon points to a vocabulary-only schema. Verify schema assignment in the source configuration.

"Concept set empty" error during generation​

The concept set referenced in the cohort expression resolved to zero concept IDs when evaluated against this source's vocabulary. This usually means the concept IDs exist in one vocabulary release but were deprecated or removed in the version loaded in this source. Update the concept set to use concepts valid in the target vocabulary version.

Data Explorer Issues​

Data Explorer shows "No Achilles results found"​

The selected data source has not had Achilles run against it, or the results schema is empty. Ask an admin to trigger an Achilles run: Admin --> System --> Achilles Jobs --> Run.

Measurements tab shows no distributions​

The measurement domain may have low record counts in this source, or the vocabulary mapping may be incomplete. Check the measurement count in the Overview tab. If the count is low, the source may not have structured lab data.

Genomics Issues​

VCF parsing errors​

"Invalid VCF header" or "Missing mandatory header line"

The uploaded file does not have a valid VCF header. Ensure the file:

  • Starts with ##fileformat=VCFv4.x on the first line
  • Contains a #CHROM header line before data rows
  • Is not compressed (upload .vcf, not .vcf.gz --- compressed files must be decompressed first)

"Unknown contig" or chromosome name warnings

VCF files using non-standard chromosome naming (e.g., 1 instead of chr1, or MT instead of chrM) will produce warnings. Parthenon normalizes common naming conventions automatically, but custom contigs will be flagged. These variants are still imported but may not map correctly to reference genome annotations.

Large VCF file upload times out​

For VCF files larger than 500 MB:

tip

Split large VCF files by chromosome using bcftools:

bcftools view -r chr1 input.vcf > chr1.vcf
bcftools view -r chr2 input.vcf > chr2.vcf
# ... repeat for each chromosome

Upload each chromosome file separately. Variants will be merged under the same upload batch.

If splitting is not practical, increase the PHP upload timeout in the server configuration or use the CLI import.

ClinVar annotation returns no results​

  • Verify the ClinVar database is loaded: check Genomics --> ClinVar Status or call GET /api/v1/genomics/clinvar/status.
  • If the status shows "not loaded," run a ClinVar sync first (POST /api/v1/genomics/clinvar/sync).
  • ClinVar annotations match on chromosome, position, reference allele, and alternate allele. If your VCF uses a different genome build (e.g., GRCh37/hg19 vs GRCh38/hg38), annotations may not match. Parthenon's ClinVar database uses GRCh38 by default.

Person matching fails for VCF samples​

The person matching step (POST /api/v1/genomics/uploads/{id}/match-persons) requires that VCF sample identifiers correspond to values in the OMOP person table (typically person_source_value). If matching fails:

  • Check that the sample names in the VCF #CHROM header line match the person_source_value in your CDM.
  • If identifiers differ, you can manually map samples to person_id values in the upload detail page.

Tumor board view is empty​

The Tumor Board requires:

  1. At least one genomic variant imported for the patient
  2. Clinical data (conditions, drugs) present in the CDM for the same person_id
  3. The patient's person_id must be linked to the VCF upload via person matching

If any of these are missing, the tumor board will show partial or empty sections.

Imaging Issues​

DICOM viewer not loading / blank viewer​

Cornerstone3D library not initializing:

  • Ensure your browser supports WebGL 2.0 (required by Cornerstone3D). Check at get.webgl.org.
  • Try a hard refresh (Ctrl/Cmd + Shift + R) to clear cached JavaScript bundles.
  • Disable browser extensions that block WebGL or GPU acceleration (some ad blockers interfere).

Image data not loading in viewer:

  • Verify the WADO-RS endpoint is accessible: GET /api/v1/imaging/wado/{sopUid} should return DICOM data.
  • Check browser developer tools (Network tab) for 404 or 500 errors on WADO requests.
  • If using a remote DICOMweb server, ensure the server is reachable from the Parthenon backend and CORS headers are configured.

WADO-RS authentication errors​

The WADO-RS endpoint (/api/v1/imaging/wado/{sopUid}) is designed to be accessible without authentication for viewer integration. If you receive 401 errors:

  • Ensure the endpoint is not behind an authentication proxy that requires credentials.
  • Check that the route is correctly excluded from Sanctum middleware in the server configuration.

DICOM import shows "0 studies indexed"​

When indexing from a DICOMweb server:

  • Verify the DICOMweb server URL is correct and accessible from the Parthenon container.
  • Check that the DICOMweb server supports QIDO-RS (Query based on ID for DICOM Objects).
  • If authentication is required, ensure credentials are configured in the imaging settings.

When importing local files:

  • Verify the directory path is accessible from within the Docker container (check volume mounts).
  • Ensure files have .dcm extension or are valid DICOM files without extension.
  • Check the Laravel Horizon queue for failed jobs --- large imports are processed asynchronously.

Imaging criteria not filtering cohorts​

Imaging criteria in the cohort builder require:

  1. Imaging studies to be indexed in Parthenon's imaging tables.
  2. Corresponding procedure_occurrence records to exist in the CDM linking patients to imaging procedures.
  3. The imaging criterion's modality and body part filters to match the indexed DICOM metadata.

If imaging criteria produce zero patients, check that the imaging metadata is properly linked to CDM records.

FHIR Sync Issues​

JWT authentication failures​

"Invalid client assertion" or "JWT signature verification failed"

SMART Backend Services authentication requires:

  1. A registered Client ID on the EHR server
  2. A private key (RS384 or ES384) that matches the public key registered with the EHR
  3. The JWT iss and sub claims must both equal the Client ID
  4. The JWT aud must be the EHR's token endpoint URL
  5. The JWT must not be expired (check server clock synchronization)
Clock Skew

JWT validation is sensitive to clock differences between the Parthenon server and the EHR server. Ensure NTP is configured and the system clock is synchronized to within 30 seconds.

"Client not authorized" or "Scope not granted"

The EHR server has not granted the requested FHIR scopes. Contact your EHR administrator to ensure the following scopes are approved for your client:

  • system/Patient.read
  • system/Condition.read
  • system/MedicationRequest.read
  • system/Procedure.read
  • system/Observation.read
  • system/Encounter.read

Bulk Data Export timeouts​

FHIR Bulk Data Export can take hours for large populations. If exports time out:

  1. Check the EHR's export status endpoint --- the export may still be running on the EHR side even if Parthenon's polling timed out.
  2. Reduce the patient scope --- use a smaller group or date filter for the initial sync, then expand.
  3. Check EHR rate limits --- some vendors limit concurrent exports or total export size.
  4. Retry --- Parthenon's sync is idempotent. Re-triggering a sync will resume from the last successful checkpoint (if supported by the EHR).

Deduplication conflicts​

"Content hash collision" warnings in sync logs

During incremental sync, Parthenon uses content hashing to avoid duplicate records. If you see hash collision warnings:

  • These are usually benign --- they indicate records that already exist in the CDM.
  • If you expect new data but see only collisions, the EHR may not be returning updated records. Check the _lastUpdated filter on the Bulk Data Export request.
  • To force a full re-sync, delete the sync run history for the connection and trigger a new sync.

FHIR resource mapping errors​

"Unmapped resource type" warnings

Parthenon maps a specific set of FHIR R4 resources to OMOP CDM tables. Resources not in the mapping list are skipped with a warning. Currently mapped resources: Patient, Condition, MedicationRequest, Procedure, Observation, Encounter, DiagnosticReport, Immunization.

"Missing required field" errors

Some FHIR resources from the EHR may lack fields required for OMOP mapping (e.g., a Condition without a code or an Observation without an effectiveDateTime). These resources are logged as errors and skipped. Review the sync run detail page for a list of skipped resources and their reasons.

Sync dashboard shows stale data​

The FHIR sync dashboard (Admin --> FHIR Sync Dashboard) caches aggregate statistics. If you just completed a sync run but the dashboard shows old numbers:

  • Wait 60 seconds for the cache to refresh.
  • Trigger a manual refresh by navigating away from the dashboard and returning.
  • Check that the sync run completed successfully (status = completed, not running or failed).

Performance Issues​

Page loads are slow​

  • Try a hard refresh (Ctrl/Cmd + Shift + R) to clear cached assets.
  • Check your network connection speed.
  • If all users report slowness, it may be a server issue --- ask your admin to check the System Health dashboard.

Cohort generation is stuck "Running" for >30 minutes​

For large databases, complex cohorts can take 30--60 minutes. If it exceeds 60 minutes, it may have stalled. Ask an admin to check the Laravel Horizon queue dashboard (/horizon) for failed or stalled jobs and retry if necessary.

API Issues​

401 Unauthorized​

Your session token has expired. Re-authenticate via POST /api/v1/auth/login.

422 Validation Error​

The request body failed validation. Check the errors field in the JSON response for field-specific messages.

429 Too Many Requests​

You have exceeded the rate limit. The login endpoint allows 5 attempts per 15 minutes per IP. Wait for the cooldown period specified in the Retry-After response header.

Reporting Bugs​

If you encounter an issue not covered here:

  1. Check the Admin --> System --> Logs page for relevant error messages.
  2. Note the URL, the action you were taking, and the exact error message.
  3. Open an issue at the project's GitHub repository with this information.

Include your Parthenon version (shown in Admin --> System --> About) in all bug reports.