Troubleshooting
The Simplitics PDQ platform includes several key components and processes that require daily operational monitoring and troubleshooting. Common problems and their resolutions, ranging from infrastructure crashes to specific data processing errors, are categorized below.
I. Infrastructure and System Stability Issues
These problems generally indicate that the underlying servers or the core application components (like the Docker containers) are not running correctly.
| Problem | Resolution / Action |
|---|---|
| Application is Down or Unreachable | Simple Fix: The most common resolution for almost all weird infrastructure-related problems (like a Virtual Machine crash) is to Stop the virtual machine and then Start the virtual machine again from the cloud portal (e.g., Azure VM or AWS EC2). |
| VM Restart Failed to Resolve Issues | Advanced Fix (Manual Docker Restart): 1. SSH into the virtual machine. 2. Check filesystem usage ( df -H); if 100% used, this is problematic.3. Check Docker state ( docker ps -a); all containers should be running.4. Navigate to /datadrive/configs and execute docker compose down followed by docker compose up -d for all components (e.g., AME, UI, DLS, DWA, INGEST, TOOLS) to shut down, clean up, and restart them. |
| System Health Status is FAIL | If the System Health tab shows any rows with a status of FAIL, then those tasks/files must be restarted. |
II. Data Ingestion and Data Flow (DLS/INGEST)
These issues relate to data moving through the initial processing layers (Landing, Raw, Trusted, Published) managed primarily by the Data Lake Service (DLS) and INGEST components.
| Problem | Resolution / Action |
|---|---|
| Inconsistent Data Volumes (DLS Trace) | Verify the DLS Trace view is set to "Last 24 Hours". If any key processing layer (Landing, Raw Archive, Trusted, Profile) shows a count that differs significantly, or reads 0, open the admin console and reload that step. |
| Missing Expected Files (Red Banner) | If the green banner ("All configured files have at least one delivery") is missing or is red, check for known exceptions in Known issues. |
| Interrupted DLS Process | If data pipelines were interrupted due to a crash: • Stuck in Raw: Filter DLS Trace by lastSeenOn = raw, open "Open admin console", and press "Load Trusted".• Stuck in Landing: Filter by lastSeenOn = landing and press "Load Raw". |
| Missing Bronze/Published Loading | If data is missing in the Bronze layer, filter the DLS Trace view by trustedNoOfFiles = 0 (or ConformedNumberOfFiles = 0). Open the admin console and press "Load Trusted" to trigger missing Bronze loading processes. |
III. Data Processing and Transformation Issues
These issues arise when the Data Modifier attempts to standardize complex data formats (XML/JSON).
| Problem | Resolution / Action |
|---|---|
| Inconsistent Data Structures | Issue: Elements (e.g., XML <attachment>) treated inconsistently as objects or lists.Resolution: The updated Data Modifier strictly enforces the structure defined in the metadata/data contract, ensuring elements are always lists if defined as such. |
| Large Files Exhaust Memory | Issue: Nested XML/JSON files exceed system memory. Resolution: Enable high-performance streaming by setting useForSplittingRecords to 1 on a specific hierarchy level in the source file metadata (via API). This processes the file chunk-by-chunk. |
| Metadata Case Mismatch | Issue: Source fields map to NULL in the database.Resolution: Attributes fieldKey and path are Case Sensitive and must match the source exactly. If target naming conventions differ, use fieldAlias and levelAlias instead. |
IV. Data Warehousing and Loading (DWA)
These issues pertain to the DWA component's orchestration and loading of data from Published/Trusted to the Integrated Core Model.
| Problem | Resolution / Action |
|---|---|
| DWA Tasks have Failed | If the Failed count is > 0, identify the failed tasks (red in list or Gantt chart). If the failure looks temporary — a network or connection issue — restart it from the DataOps Console. |
| Batch schedules run before data existed | If data is late or missing because of timing, mark the relevant tasks (all of them for a specific schedule and sourcefile) and use "Restart Tasks". |
| Job Stuck in 'Scheduled' | If the Scheduled count is > 0 and the job has been stuck for more than 2 hours, mark the relevant tasks (all of them for a specific schedule and sourcefile) and use "Restart Tasks". |
| Unnecessary DWA Schedule Created | If a file-triggered task is created but no CORE model loadings depend on it, stop the schedule using the API: POST /api/v2/master/schedule/{sourcefile} (set a ValidTo date). |
| DWA Loading Skipped/No SQL Generated | Missing key mappings usually cause this. • Object Load: Requires complete key mapping. • Attribute Load: Requires key mapping + attribute mapping. • Relationship Load: Requires mapping of two complete keys from the same source within the same mapping group. |
Related pages
| Known issues | Product defects and limitations that are known, expected and not yet fixed — with their status and any planned fix. |
| FAQ | Answers to the questions that come up most often. |
| DataOps Console | What each console page shows and which corrective actions it offers. |
This page is the operational runbook: what to do, right now, when a daily check fails. Known issues covers why a class of failure happens and whether a fix is coming.