Saltar al contenido principal

Troubleshooting

This guide covers the most common issues encountered in TietAI, with specific steps to diagnose and resolve each one.

Workflow execution failed​

How to find the error​

  1. Go to Hydra Builder → Workflows and click the workflow that failed
  2. In the Execution panel at the bottom, find the failed execution (red status badge)
  3. Click the execution row to open the detail view
  4. The canvas overlay shows each node with a colored badge: green (success), red (error), gray (not reached)
  5. Click the red node to open its detail panel
  6. Click the Error tab — this shows the full error message, the error category, and usually a suggested fix

Error categories​

Connector errors​

What it looks like: ConnectorError: Failed to reach Epic FHIR endpoint. Status: 401 Unauthorized

Common causes:

  • API credentials expired (Epic tokens have expiry periods)
  • The connector user's password was changed in the EHR system
  • The EHR system's maintenance window is active

Fix steps:

  1. Go to Settings → Connectors
  2. Find the connector referenced in the error message
  3. Click ... → Test Connection
  4. If the test fails, click Edit and update the credentials
  5. After saving, click Test Connection again to confirm the fix
  6. Re-run the failed workflow

Data errors​

What it looks like: ValidationError: Required field 'Patient.identifier' is missing in 3 records

Common causes:

  • The source system is returning incomplete records (missing mandatory FHIR fields)
  • A FHIR Transform node is configured with strict validation, and incoming data does not meet the requirements
  • An AI Agent node is producing output that does not match the expected format for the downstream node

Fix steps:

  1. Click the failing node in the execution detail view and open its Input tab
  2. Review the actual data that arrived at the node — identify which records are malformed
  3. Add a Filter node upstream to exclude records missing required fields, or
  4. Add a FHIR Transform node configured to add default values for missing fields
  5. If the issue is in an AI Agent's output, refine the prompt to instruct the model to always include required fields in the expected format

Timeout errors​

What it looks like: TimeoutError: Node 'Clinical Summarizer' exceeded execution limit of 30 minutes

Common causes:

  • Workflow is processing more records than expected (e.g., an unfiltered patient list with thousands of patients)
  • The AI model endpoint is slow or under load
  • A downstream FHIR server is responding slowly

Fix steps:

  1. Add a Filter or Batch node upstream of the slow node to reduce the number of records it processes at once
  2. Open the node's configuration → Advanced → increase the Node timeout setting
  3. If the model endpoint is slow, try switching to a faster model variant in the AI node's config
  4. If the FHIR server is slow, check its health in Settings → Connectors → Test Connection
  5. For large datasets, consider running the workflow on a smaller date range and iterating

Permission errors​

What it looks like: PermissionError: Epic user 'svc_tietai' does not have access to MedicationRequest resources

Common causes:

  • The connector service account in the EHR does not have the required FHIR resource permissions
  • A FHIR scope was not granted in the Epic MyApps registration
  • The patient is restricted (VIP patient, minors with special privacy settings)

Fix steps:

  1. Note the exact resource type mentioned in the error (e.g., MedicationRequest)
  2. Work with your Epic administrator to grant the service account access to that resource type
  3. For Epic specifically: check the App Orchard registration to confirm the required FHIR scopes are enabled for your application
  4. For restricted patients: this is expected behavior. Add an Error Handler node to gracefully skip restricted patients and log them separately

Cannot connect to EHR​

Possible cause 1: Incorrect base URL​

Verify the URL by opening it in a browser. A correct Epic FHIR URL returns a JSON CapabilityStatement document. A wrong URL returns a 404 or an HTML error page.

Correct format examples:

https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
https://fhir.cerner.com/<tenant-id>/r4

Common mistakes: trailing slash at the end, wrong path suffix, using the patient-facing portal URL instead of the API URL.

Possible cause 2: Expired credentials​

Epic client credentials do not expire automatically, but the private key associated with your MyApps registration can be rotated. If your Epic team has rotated keys, you must upload the new private key in Settings → Connectors → [your connector] → Edit.

Possible cause 3: Network / firewall blocking outbound connections​

TietAI's servers make outbound HTTPS requests to your EHR's API endpoint. If your EHR requires IP allowlisting, provide your TietAI account manager with TietAI's egress IP ranges for your region (available from Settings → Organization → API Info) so they can be added to your EHR's allowlist.

Possible cause 4: MyApps registration not approved for Production​

Your registration may have been approved for the Sandbox environment only. Confirm with your Epic App Orchard contact that Production access has been granted.

Possible cause 5: EHR system in maintenance​

Some EHRs take scheduled maintenance windows (often overnight). Check with your EHR team whether a maintenance window is active.

Patient data is not syncing​

Step 1: Check your sync workflow's execution history Go to Hydra Builder → Workflows, find your EHR sync pipeline, and open the Executions panel. Check the last execution:

  • Did it run? If no recent execution exists, the workflow may not be scheduled. Click Run to trigger a manual sync.
  • Did it complete? If the status is Failed, follow the "Workflow execution failed" steps above.

Step 2: Check connector health Go to Settings → Connectors and run Test Connection on the connector used by your sync workflow. A failed test means the EHR is unreachable — resolve the connector issue first.

Step 3: Trigger a manual sync for a specific patient If the workflow is healthy but a specific patient's record seems out of date, open that patient's detail view and click Sync Now in the top-right corner.

Step 4: Check for filter issues If the workflow uses a Filter node, the patient you are looking for may be excluded by the filter criteria (e.g., filtered to "Active" patients only, and the patient's status is "Inactive" in Epic).

AI agent produces unexpected output​

Tip 1: Inspect the model input in the execution detail Open the failing execution, click the AI Agent node, and view the Input tab. Confirm the data reaching the agent is what you expect. If the input is malformed, the issue is upstream.

Tip 2: Review and simplify the prompt Open the AI Agent node config. If the prompt is long or ambiguous, the model may misinterpret it. Test with a simpler prompt first, then add complexity back incrementally.

Tip 3: Adjust model parameters

  • Temperature — If output is inconsistent or creative when you need factual, structured output, lower the temperature (0.0–0.3 for deterministic tasks, 0.7–1.0 for creative tasks)
  • Max tokens — If the model is cutting off its response mid-sentence, increase the max tokens setting
  • System prompt — Add explicit instructions about output format (e.g., "Always respond in valid JSON with exactly these fields: ...")

Tip 4: Check for token limit issues If the input data is very large (thousands of patients or long clinical notes), the model may hit its context window limit. Use a Batch node upstream to process data in smaller chunks, or a Filter node to reduce input size.

Application is slow or unresponsive​

Browser cache: Clear your browser cache (Ctrl+Shift+Delete in Chrome/Firefox) and reload. Stale cached assets can cause rendering issues after platform updates.

Try incognito mode: Open TietAI in an incognito/private window with no extensions. If this resolves the issue, a browser extension is interfering.

Network check: Open your browser's developer tools (F12) → Network tab → reload the page. Look for requests that are taking more than 5 seconds or returning errors. If the TietAI API is timing out, the issue may be server-side — check the TietAI status page for active incidents.

Canvas performance: If the Hydra Builder canvas is slow with a large workflow (50+ nodes), try zooming out to reduce rendered DOM elements, or split the pipeline into multiple smaller workflows linked by a trigger.

Getting help​

If you cannot resolve an issue using this guide, contact TietAI support. Include the following information to get a faster resolution:

  • Organization name and the name of the affected user (if not you)
  • Execution ID — visible in the URL when viewing a failed execution (e.g., exec_abc123), or in the execution panel
  • Connector name — if the issue is connector-related
  • Screenshot of the error message shown in the execution detail view or the UI
  • What you were trying to do and what you expected to happen
  • Timestamp of when the issue occurred (include timezone)

Contact options: Help → Contact Support in-app, or email support@tiet.ai.