299003 - Device Is Unreachable

Agent error code #299003 means the agent could not connect to the device behind this knoc, so it is holding back changes to it for a short time. The agent reported this without contacting the device.

The agent pauses a knoc after two operations in a row fail to connect to its device: the connection timed out, was refused, found no route, or the device's name did not resolve. The first pause lasts two minutes. The first operation to arrive after that is sent to the device as a check. If it cannot connect either, the pause doubles, up to a limit of fifteen minutes. Any answer from the device ends the pause straight away, including an error.

A device that accepts the connection and then answers slowly is not paused. That is usually a firewall busy with a commit, and it gets the agent's normal timeout and retry instead.

While a knoc is paused:

• Revokes fail with this code. Once the device answers again, or the pause runs out, the agent asks the server to send them again and removes the addresses then. Until that happens, the address may still have access on the device.
• Grants are always sent to the device, so a user gets access whenever the device can take it. A grant that goes through ends the pause for the revokes too.
• A full resync of the knoc (after the agent reconnects, for example) sends one grant to the device as a check. If it cannot connect, the resync's other grants and revokes fail with this code instead of each waiting out a connection timeout. The next grant for each address re-applies it.

The pause exists because the agent handles each backend type one operation at a time. A device that is not there holds up every operation for that type while each one waits to connect, including operations for other devices that are working.

Steps to Resolve

Check the Agent Can Reach the Device

1. On the agent's host, confirm the device's management address answers, for example by opening its API URL with curl
2. Check the address and port configured on the integration
3. Check for a firewall rule, route or VPN change between the agent and the device
4. Check the device itself is up

Once the device answers again, the next operation the server sends clears the pause, and the agent retries the revokes it held back within a minute or so. If nothing else arrives for the knoc, the agent retries them when the pause runs out. Nothing on the agent needs restarting.

Find the Original Error

The agent log records why it paused the knoc, with the connection error beside it. Look for "could not connect to device on consecutive operations". That error's code links to the vendor-specific steps.