OPN002 - OPNsense Request Timed Out

Agent error code #OPN002 indicates that an OPNsense API call did not complete within the agent's timeout window. The firewall accepted the connection but did not return a response in time.

This error is distinct from connection failures (#OPN004) and DNS failures (#OPN005), which occur before any request reaches the firewall. Error #OPN002 means the firewall was contactable but slow to respond.

Common causes include:

• The OPNsense host is under heavy load and slow to handle API requests
• The alias being modified has grown very large, slowing the reconfigure step
• A network device between the agent and OPNsense is rate-limiting or shaping traffic
• The firewall is mid-reload from another configuration change

Steps to Resolve

Confirm OPNsense Is Responsive

1. From the agent host, run curl -sk -u <key>:<secret> https://<host>/api/firewall/alias_util/list/<alias> and measure the response time
2. If the same request takes several seconds from the command line, the firewall itself is slow and the underlying cause needs investigation

Check Network Path

1. Confirm the agent host can reach the firewall hostname and port over the network
2. Look for any shaping, proxying, or VPN hops between the agent and the firewall that might add latency
3. Verify there is no asymmetric routing causing TCP retransmissions

Retry the Operation

1. Grants are idempotent. Retry the operation by logging the affected user in again
2. If the timeout persists, log into OPNsense directly to confirm the firewall is healthy and no background reload is in progress

Still Having Issues?

We can help you out, contact us at support@knocknoc.io.