Rela AIRela AI Docs

Troubleshooting

Guide for solving common issues in Rela AI.

Troubleshooting

This guide covers the most common issues when using Rela AI and how to resolve them.

WhatsApp Connection Issues

QR code does not appear

Cause: The WhatsApp server cannot generate the session, usually due to a network issue or an already active session.

Solution:

  1. Check that your internet connection is stable.
  2. If you already had an active session, disconnect it first from the control panel.
  3. Reload the page and request the QR code again.
  4. If the problem persists, wait 2-3 minutes before retrying. WhatsApp enforces rate limits.

The agent disconnects frequently

Cause: WhatsApp closes inactive sessions or when it detects multiple connections from the same number.

Solution:

  1. Make sure you do not have WhatsApp Web open in another browser or device at the same time.
  2. Verify that your phone has a stable internet connection.
  3. Reconnect the agent from the dashboard and scan the QR again.

Messages do not reach the agent

Cause: The WhatsApp session is disconnected or the webhook is not configured correctly.

Solution:

  1. Check the agent's connection status in the dashboard. It should show "Connected".
  2. If it appears disconnected, reconnect by scanning the QR code.
  3. Verify that the destination number is not blocked.
  4. Review the agent logs to confirm that messages are being received.

Email Issues

Email account does not verify

Cause: DNS records (SPF, DKIM, MX) are not configured correctly on your domain.

Solution:

  1. Go to the email agent configuration and copy the required DNS records.
  2. Access your domain administration panel (GoDaddy, Cloudflare, etc.).
  3. Add the TXT records for SPF and DKIM exactly as shown.
  4. Add the MX record pointing to the Rela AI server.
  5. Wait up to 48 hours for DNS propagation. You can check the status with tools like MXToolbox.

DNS records are configured but verification fails

Cause: Incomplete DNS propagation or incorrectly formatted records.

Solution:

  1. Check that there are no extra spaces or invisible characters in the records.
  2. Confirm that the TTL is not excessively high (recommended: 3600 or less).
  3. Use dig TXT yourdomain.com or MXToolbox to confirm the records are visible.
  4. If using Cloudflare, make sure the proxy is disabled for email records.

Emails sent by the agent do not reach the recipient

Cause: Emails may be marked as spam or DNS records are incomplete.

Solution:

  1. Ask the recipient to check their spam/junk folder.
  2. Verify that SPF and DKIM are correctly configured.
  3. Check the agent logs to confirm the email was sent successfully.
  4. If the domain is new, it may need time to build reputation. Send test emails first.

Event and Alarm Issues (Machine Agents)

Events are not processed

Cause: The connection to the MQTT broker or OPC UA server is interrupted, or the event format is invalid.

Solution:

  1. Check the machine agent's connection status in the dashboard.
  2. Confirm that the MQTT broker credentials (host, port, username, password) are correct.
  3. Verify that the MQTT topic the agent is subscribed to is correct.
  4. Check that the event payload is valid JSON.

MQTT connection fails

Cause: Port blocked by firewall, incorrect credentials, or broker unavailable.

Solution:

  1. Verify that port 1883 (or 8883 for TLS) is open on your firewall.
  2. Test the connection manually with an MQTT client such as MQTTX or mosquitto_sub.
  3. Confirm the broker is running and accepting external connections.
  4. If using TLS, verify that certificates are valid and not expired.

OPC UA connection fails

Cause: Incorrect endpoint URL, untrusted certificates, or incompatible security policy.

Solution:

  1. Verify that the OPC UA endpoint URL is accessible from the Rela AI server.
  2. Confirm that the configured security policy matches the OPC UA server's policy.
  3. If the server requires certificates, ensure they are correctly installed.
  4. Review the logs for specific OPC UA protocol error messages.

Tool Issues

The tool does not execute

Cause: The tool schema is misconfigured, the endpoint is not responding, or the agent does not have the tool assigned.

Solution:

  1. Verify that the tool is assigned to the agent in the configuration section.
  2. Confirm that the endpoint URL is accessible and responds correctly.
  3. Test the endpoint manually with a tool like Postman or curl.
  4. Check that the JSON parameter schema is valid.

Parameters are sent incorrectly

Cause: The parameter schema does not match what the endpoint expects, or the tool description is ambiguous for the AI model.

Solution:

  1. Review the tool's schema definition. Each parameter should have a type, description, and required flag.
  2. Improve parameter descriptions so the AI model can correctly infer the values.
  3. Use the tool's description field to clearly explain when and how it should be used.
  4. Check the logs to see what parameters the agent is sending to the endpoint.

Data Extraction Issues

The document does not process

Cause: Unsupported file format, corrupted file, or excessive file size.

Solution:

  1. Verify that the file is a PDF, image (PNG, JPG), or a supported format.
  2. Confirm the file size does not exceed the limit (typically 10 MB).
  3. If it is a scanned PDF, ensure the image quality is readable.
  4. Try a different version of the document or convert it to PDF.

Fields are not detected correctly

Cause: The document structure does not match the extraction template, or the document quality is low.

Solution:

  1. Review the extraction structure (report_structure) and confirm that the key_value labels match the document labels.
  2. If the document has a non-standard format, adjust the field descriptions in the template.
  3. Improve document quality: higher resolution, no watermarks, legible text.
  4. Test with sample documents to validate the template before using it in production.

General Issues

Session expires constantly

Cause: The authentication token has a limited lifespan or there are browser cookie issues.

Solution:

  1. Log out and log back in.
  2. Clear browser cookies and cache for the Rela AI domain.
  3. Verify that your system clock is correctly synchronized.
  4. If using a VPN, try without it to rule out network issues.

Permission error ("Unauthorized" or "Forbidden")

Cause: Your role in the organization does not have the necessary permissions for the requested action.

Solution:

  1. Check your current role in the Organization section of the dashboard.
  2. Contact your organization administrator to request the necessary permissions.
  3. Available roles are: Admin, Manager, and Viewer. Only Admin and Manager can modify agents.

API Rate Limiting

Cause: The maximum number of allowed requests in a time period has been exceeded.

Solution:

  1. Wait a few minutes before retrying. Limits reset automatically.
  2. If using the API directly, implement retry logic with exponential backoff.
  3. Check the X-RateLimit-Remaining and X-RateLimit-Reset response headers to manage your requests.
  4. If you need higher limits, contact the support team.

Maintenance Issues

Plan executed but no task was created

Cause: The maintenance plan does not have a department assigned, so the system cannot determine who to assign the task to.

Solution:

  1. Go to the maintenance plan in question.
  2. Verify that the department_id field is correctly assigned.
  3. Save the plan and wait for the next scheduled execution.

Notification not sent

Cause: The assigned person does not have an email or phone number configured in their profile.

Solution:

  1. Go to the user's profile in the Organization section.
  2. Verify that they have a registered email or phone number.
  3. Save the changes and retry the action that triggers the notification.

Plan does not execute automatically

Cause: The plan is disabled or paused.

Solution:

  1. Open the maintenance plan.
  2. Verify that the Enabled toggle is active.
  3. Confirm that the plan is not in a Paused state.
  4. Check that the schedule (cron or date) is correct and has not passed.

Counter does not trigger

Cause: The counter_threshold value is 0 or not configured.

Solution:

  1. Open the counter-based maintenance plan.
  2. Verify that counter_threshold is greater than 0.
  3. Confirm that the asset's counter is incrementing correctly.

LOTO (Lockout/Tagout) Issues

"No approved procedure"

Cause: A LOTO execution is being initiated but no approved procedure exists for the asset.

Solution:

  1. Go to the LOTO section and create a procedure for the asset.
  2. Complete all required steps in the procedure.
  3. Submit the procedure for approval and wait for it to be approved.
  4. Once approved, you can start the LOTO execution.

Asset remains locked

Cause: The LOTO execution was not properly completed.

Solution:

  1. Go to /loto/executions/{id} where {id} is the active execution ID.
  2. Click Unlock to release the asset.
  3. Verify that all unlocking steps have been completed.

Cannot abort execution

Cause: The abort request requires a body with the cancellation reason.

Solution:

  1. When making the abort request, include a body with the reason field.
  2. Example: {"reason": "Emergency resolved, no longer needed"}.
  3. The reason is mandatory for audit purposes.

Inspection Issues

Checkpoints are not saved

Cause: Checkpoints are lost if progress is not saved before completing or leaving the page.

Solution:

  1. Click Save periodically while completing checkpoints.
  2. Do not close the page without saving first.
  3. If you lost data, you will need to re-complete the affected checkpoints.

Cannot complete the inspection

Cause: All checkpoints must have a pass or fail mark before the inspection can be completed.

Solution:

  1. Review all inspection checkpoints.
  2. Mark each one as Pass or Fail.
  3. Once all are marked, the Complete button will become enabled.

Template without checkpoints

Cause: The inspection template was created without adding checkpoints.

Solution:

  1. Edit the inspection template.
  2. Add the necessary checkpoints in the corresponding section.
  3. Save the template before using it to create inspections.

ML Anomaly Issues

"Insufficient data" when training

Cause: The anomaly detection model needs a minimum amount of historical data to train.

Solution:

  1. Ensure the asset has at least 10 historical readings recorded (ideally 100 or more).
  2. Wait for enough data to accumulate before attempting training.
  3. Verify that readings are arriving correctly to the system.

Model does not detect anything

Cause: The model sensitivity is configured too low for the current data.

Solution:

  1. Go to the anomaly model configuration.
  2. Change the sensitivity to high to detect smaller deviations.
  3. Re-train the model if necessary.
  4. Verify that the input data has sufficient variability.

Too many false positives

Cause: The model sensitivity is too high, detecting normal variations as anomalies.

Solution:

  1. Reduce the sensitivity to low in the model configuration.
  2. Re-train the model with a more representative dataset.
  3. Review and dismiss false anomalies to improve model learning.

SPC (Statistical Process Control) Issues

"Invalid chart_type"

Cause: The SPC chart type must use the format with underscores, not hyphens or spaces.

Solution:

  1. Use valid values: x_bar_r, x_bar_s, i_mr.
  2. Do not use formats like x-bar-r, xBarR, or X Bar R.
  3. Verify the exact value in the API documentation.

No control limits

Cause: The system needs a minimum amount of data to calculate control limits (UCL, LCL).

Solution:

  1. Record at least 10 subgroups of data before expecting calculated limits.
  2. Ideally, use 25 or more subgroups for more stable limits.
  3. Limits are calculated automatically once there is enough data.

Capability (Cp/Cpk) shows "—"

Cause: The specification limits (USL and LSL) are not defined on the SPC chart.

Solution:

  1. Edit the SPC chart.
  2. Define the USL (Upper Specification Limit) and the LSL (Lower Specification Limit).
  3. Save the changes. The Cp and Cpk indices will be calculated automatically.

Need more help?

If your issue is not covered in this guide:

  • Check the agent logs in the dashboard for error details.
  • Contact the support team through the in-platform chat.
  • Send an email to soporte@rela-ai.com with a description of the issue, screenshots, and relevant logs.

Admin API

Billing, SSO, audit, notifications, and escalation rules endpoints.

Glossary

Definitions of technical terms used in Rela AI.

On this page

TroubleshootingWhatsApp Connection IssuesQR code does not appearThe agent disconnects frequentlyMessages do not reach the agentEmail IssuesEmail account does not verifyDNS records are configured but verification failsEmails sent by the agent do not reach the recipientEvent and Alarm Issues (Machine Agents)Events are not processedMQTT connection failsOPC UA connection failsTool IssuesThe tool does not executeParameters are sent incorrectlyData Extraction IssuesThe document does not processFields are not detected correctlyGeneral IssuesSession expires constantlyPermission error ("Unauthorized" or "Forbidden")API Rate LimitingMaintenance IssuesPlan executed but no task was createdNotification not sentPlan does not execute automaticallyCounter does not triggerLOTO (Lockout/Tagout) Issues"No approved procedure"Asset remains lockedCannot abort executionInspection IssuesCheckpoints are not savedCannot complete the inspectionTemplate without checkpointsML Anomaly Issues"Insufficient data" when trainingModel does not detect anythingToo many false positivesSPC (Statistical Process Control) Issues"Invalid chart_type"No control limitsCapability (Cp/Cpk) shows "—"Need more help?