Module - Host Agent
Module - Host Agent
Breadcrumbs

Troubleshooting & Support

Troubleshooting & Support

Troubleshooting Approach

Work from the outside in:

  1. Confirm module and Host Client versions.

  2. Confirm that the module is enabled and the Host Client service is running.

  3. Confirm network reachability and certificate validity.

  4. Confirm that the host is both connected and trusted.

  5. Confirm that the required mapping is active and has the correct access mode.

  6. Distinguish command submission from acknowledgement and completed result.

  7. Allow fresh state to arrive after any module, Gateway, or Host Client restart.

Do not bypass certificate validation, identity checks, Ignition access control, or host-side mapping approval while troubleshooting.

Common Problems

Module Does Not Start

Symptoms

  • Factory Host Agent is absent or disabled.

  • Gateway pages or the managed tag provider are unavailable.

Possible Causes

  • The module was not installed or enabled.

  • The Gateway is not running the required Ignition version.

  • The unsigned artifact is blocked by deployment policy.

Recommended Checks

  • Review the Gateway module status.

  • Confirm Factory Host Agent 3.0.0 and the Ignition 8.3.0 baseline.

  • Review Gateway logs for module-loading errors without publishing sensitive values.

Resolution

Correct the compatibility or policy issue, install through the standard Ignition module workflow, and enable the module.

Configuration Is Not Applied

Symptoms

  • A socket-related setting was saved but behavior did not change.

  • A visible feature toggle has no effect.

Possible Causes

  • Socket settings require a module or Gateway restart.

  • The selected setting is displayed but not active in this release.

Recommended Checks

  • Review the behavior table in User Guide & Components.

  • Confirm whether the setting is active.

  • Confirm that a controlled restart occurred after changing a socket setting.

Resolution

Restart the module or Gateway when required. Do not rely on settings listed as inactive.

Host Does Not Appear

Symptoms

  • No pending or connected host is shown.

Possible Causes

  • Start gateway service was not selected.

  • The setup bundle is missing or does not match the intended Gateway.

  • The host cannot reach the Gateway URL.

  • A reverse proxy supplied an unusable external address.

  • Certificate validation failed.

Recommended Checks

  • Confirm the Host Client service is running.

  • Confirm the bundle came from the intended Gateway.

  • Test reachability to the configured Gateway scheme, host, and port.

  • Check the Host Client status phase and message.

  • Validate reverse-proxy and certificate configuration.

Resolution

Correct the Gateway external address, proxy, firewall, or certificate issue. Generate a fresh setup bundle after correcting the externally visible URL.

Enrollment Remains Pending

Symptoms

  • The host appears but never becomes trusted.

Possible Causes

  • The host was not approved.

  • The Host Client service stopped before it could observe approval.

  • The enrollment credential expired before initial enrollment.

  • The local trust state is terminal.

Recommended Checks

  • Confirm that an administrator approved the correct pending host.

  • Confirm the Host Client service is still running.

  • Review the Host Client trust state and message.

Resolution

Approve the verified host or generate a new setup bundle for an expired initial enrollment. Terminal rejected, expired, or revoked states require a controlled re-provisioning process; no self-service reset is provided.

Connected Host Has No Current Data

Symptoms

  • The host shows connected, but telemetry or permissions are missing.

Possible Causes

  • Trust is not established.

  • Fresh snapshots have not arrived after restart.

  • The connection is stale.

Recommended Checks

  • Confirm both connected and trusted state.

  • Check heartbeat age.

  • Request host, process, or permission refresh from Commands.

  • Inspect acknowledgements.

Resolution

Keep the Host Client service running and allow it to republish current state. Runtime data from before a module restart is not restored.

Expected File or Directory Is Missing

Symptoms

  • A mapped resource is absent or an operation is denied.

Possible Causes

  • The mapping is inactive, too narrow, or read-only.

  • A more-specific mapping determines effective access.

  • Recursion does not cover the target.

  • The resolved path leaves the approved area or passes through an unsupported link.

Recommended Checks

  • Review the exact mapping, recursion, and access mode.

  • Confirm a fresh permission snapshot reached the Gateway.

  • Confirm source and destination are both authorized for a move.

  • Confirm the Host Client process has native filesystem access.

Resolution

Adjust the narrowest appropriate mapping and have the host operator approve it. Do not broaden access solely to work around a path error.

Serial Port Is Missing or Does Not Connect

Symptoms

  • A physical port is absent from tags.

  • Apply or connect does not produce the expected device state.

Possible Causes

  • No active mapping covers the port.

  • The device identity changed or the device is disconnected.

  • Another application holds the port.

  • Communication settings are incompatible with the device.

  • The Host Client process lacks operating-system access.

Recommended Checks

  • Confirm operating-system discovery and permissions.

  • Confirm a matching specific or intentionally broad serial mapping.

  • Check desired configuration, actual state, and acknowledgement separately.

  • Confirm the port is not in use elsewhere.

Resolution

Correct the mapping, native permissions, device connection, or communication settings, then apply and verify the reported state.

Certificate or Protected-Transport Failure

Symptoms

  • The Host Client repeatedly fails before reaching pending or trusted state.

  • The status message indicates certificate or hostname validation failure.

Possible Causes

  • The URL hostname does not match the certificate.

  • The issuing chain is not trusted by the host operating system.

  • Reverse-proxy termination or external-address information is incorrect.

Recommended Checks

  • Verify the configured hostname and certificate names.

  • Verify that the complete issuing chain is trusted.

  • Verify external scheme and host handling at the proxy.

Resolution

Install the appropriate organizational trust through managed operating-system processes or use a suitable trusted certificate. Regenerate the setup bundle after correcting the external URL. The product does not provide an insecure certificate bypass.

Approved Mapping Does Not Update at the Gateway

Symptoms

  • The host operator approved a request, but the Gateway still shows old permissions.

Possible Causes

  • The Host Client service is stopped or disconnected.

  • The decision is queued locally.

  • The Gateway restarted and is waiting for a fresh snapshot.

Recommended Checks

  • Confirm the Host Client service is running and connected.

  • Wait for the next snapshot and refresh the Gateway view.

  • Check whether a more-specific mapping affects the result.

Resolution

Restore the connection and allow the queued decision and current permission snapshot to reach the Gateway.

File Command Times Out

Symptoms

  • A scripting or Gateway file operation reports a timeout or uncertain result.

Possible Causes

  • The host disconnected during the operation.

  • The command completed remotely but its final result was not received.

  • The requested operation conflicted with existing filesystem state.

Recommended Checks

  • Inspect acknowledgements and transfer results.

  • Verify the destination directly when safe.

  • Confirm the active mapping and access mode.

Resolution

Treat the final state as unknown until verified. Avoid immediately repeating create, move, or delete operations. The Cancel control does not interrupt active synchronous work.

Diagnostics

Use:

  • HostAgent Status for connection, trust, heartbeat, and current details;

  • Activity Audit for recent in-memory events;

  • Commands for refresh requests, acknowledgements, and file-transfer status;

  • Host Client Status for phase, trust, message, and counters; and

  • the pfce_host_agents provider for tag quality and current projected state.

Logging

Use standard Ignition Gateway logs for module-loading and runtime errors. Sanitize logs before sharing them.

The Host Client's Logs page and View connection logs action do not provide an integrated log viewer in version 0.1.0.

Last updated: