207101 - Failed to Read OPNsense Alias Contents

Agent error code #207101 indicates that the agent could reach the alias listing endpoint on OPNsense but the response was unexpected (non-2xx HTTP status or malformed body). The lookup is required before every grant and revocation, so this error blocks alias updates.

This error is distinct from alias-not-found (#207100), which returns a clean HTTP 404. Error #207101 means OPNsense responded with something else that the agent could not parse as a valid alias listing.

Common causes include:

• OPNsense is mid-restart or mid-reload and serving an interim response
• A proxy or load balancer in front of OPNsense returned a non-OPNsense error body
• The firewall is reporting an internal error (HTTP 5xx)
• The API user's privileges were modified mid-operation

Steps to Resolve

Reproduce the Lookup Manually

1. From the agent host, run the same lookup the agent uses:

   curl -sk -u <key>:<secret> https://<host>/api/firewall/alias_util/list/<alias>
   

2. Confirm the response is a JSON body containing alias entries

Check the OPNsense Status

1. Log into OPNsense and confirm no configuration apply is in progress under Firewall > Aliases
2. Check the OPNsense system log under System > Log Files > General for warnings around the time of the failure

Confirm API User Privileges Have Not Changed

1. If the alias is now returning 403 in the curl reproduction, the API user has lost privileges (see #207001)
2. Restore the privileges on the user's group, then retry the operation