Skip to main content

Troubleshooting

Common issues and their solutions when running the Haltless edge agent.

Connection issues​

Agent cannot reach the API​

Symptoms: Connection refused or timeout errors in agent logs.

Solutions:

  1. Verify outbound HTTPS is allowed: curl -v https://api.haltless.io/health
  2. Check proxy settings: set HTTPS_PROXY if you're behind a corporate proxy
  3. Verify DNS resolution: nslookup api.haltless.io
  4. Check firewall rules , only outbound port 443 is needed

401 Unauthorized​

Symptoms: Agent receives 401 on ingestion or heartbeat.

Solutions:

  1. Verify the API key is correct and hasn't been revoked
  2. Check for trailing whitespace in the key
  3. Confirm the key hasn't expired (expires_at field)
  4. Generate a new key via Settings > API Keys in the dashboard

402 Payment Required​

Symptoms: Heartbeat returns 402.

Solutions:

  • Your subscription is inactive or past the grace period
  • Check billing status in the dashboard under Settings > Billing
  • Update your payment method to restore access

429 Too Many Requests​

Symptoms: Ingestion requests are rate-limited.

Solutions:

  1. Check the Retry-After header for when to retry
  2. Reduce push frequency or batch size
  3. Consider upgrading your tier for higher limits:
    • Free: 60 writes/min
    • Pro: 300 writes/min
    • Enterprise: 1,200 writes/min

Data issues​

Readings rejected with "Machine not found"​

The machine_identifier in your readings must match a registered machine exactly.

  1. List your machines: GET /api/v1/machines
  2. Check for case sensitivity , identifiers are case-sensitive
  3. Register the machine first via the dashboard or API

Readings rejected with "Value must be finite"​

Sensor values must be finite numbers. NaN, Infinity, and -Infinity are rejected.

  • Check your data source for fault conditions that output non-finite values
  • Add a filter in your agent configuration to skip invalid readings

Readings rejected with timestamp errors​

  • "Timestamp too far in the future" , clock skew exceeds 5 minutes. Sync your edge device clock with NTP.
  • "Timestamp too old" , reading exceeds your tier's retention window

Duplicate readings​

Haltless deduplicates based on (machine_id, metric_name, timestamp). Sending the same reading twice won't create duplicates but also won't return an error.

OPC-UA issues​

Connection timeout​

  1. Verify the OPC-UA server is running: telnet <host> <port>
  2. Check the endpoint URL format: opc.tcp://host:port
  3. Verify security settings match the server's requirements
  4. Try security_mode = "None" for testing (not production)

BadNodeIdUnknown​

The node ID doesn't exist on the server. Use an OPC-UA browser tool (e.g., UaExpert, Prosys OPC UA Browser) to verify node IDs.

Certificate errors​

For SignAndEncrypt mode, ensure:

  • The agent's certificate is trusted by the OPC-UA server
  • The server's certificate is trusted by the agent
  • Certificates are not expired

Modbus issues​

No response from device​

  1. Verify network connectivity: telnet <host> 502
  2. Check the unit_id (slave address) matches the device
  3. Ensure the device supports Modbus TCP (not just RTU)

Incorrect values​

  1. Verify register addresses in the device documentation
  2. Check register_type , holding (FC 03) vs input (FC 04)
  3. Adjust scale and offset values
  4. Check register byte order (big-endian vs little-endian)

Performance tuning​

High memory usage​

  • Reduce max_buffer_mb if offline buffer is growing too large
  • Reduce the number of concurrent data sources
  • Decrease batch_size to reduce per-request memory

Slow data push​

  • Increase batch_size to reduce HTTP overhead (up to 1,000)
  • Check network latency to api.haltless.io
  • Ensure the buffer directory is on fast storage (SSD preferred)

Getting help​

If you can't resolve an issue:

  1. Collect agent logs: journalctl -u haltless-agent --since "1 hour ago"
  2. Note the error message and HTTP status code
  3. Contact support at support@haltless.io with:
    • Agent version
    • Configuration (redact API keys and passwords)
    • Relevant log excerpts
    • Error screenshots from the dashboard