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 categorised below.
I. Infrastructure and system stability
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 (AME, UI, DLS, DWA, INGEST, TOOLS) to shut down, clean up, and restart them. |
| System degraded | If System Health shows any rows with a status of FAILED, 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 lower than the previous zone, 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: Check the file size first — a very large file that caused an out-of-memory crash has to be split into smaller subsets before it will load. Then filter by lastSeenOn = landing and press "Load Raw". |
| Missing Trusted load | If data is missing in Trusted, filter the DLS Trace view by trustedNumberOfFiles = 0. Open the admin console and press "Load Trusted". Zone names are configurable, so an installation may label that field with its own zone name. |
III. Data processing and transformation
These issues arise when the Data Modifier attempts to standardise 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 through Base into the 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 an On file arrival task is created but no Core model loadings depend on it, stop the schedule from the console — Task Orchestration → ⋮ → ⏹ Disable — or through the API: POST /api/v3/master/schedule/{sourcefile} (set a ValidTo date). |
| DWA Loading Skipped/No SQL Generated | Missing key mappings usually cause this — see Silent failure modes. • 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.