Troubleshooting & FAQ

These are ordered by how often they come up. Each one starts with the check that distinguishes the likely cause from the rest, because the most common mistake with any of them is acting before looking.

A device shows offline but it is definitely up

Almost always this is one of two things: the probe cannot reach it, or the device is owned by an integration and the status is coming from somewhere other than the probe.

1. 1
   Check whether it is integration-owned

   A device sourced from Proxmox, vSphere, Meraki, UniFi or a cloud provider derives status from that API. For these, a failed probe on a management address is not a reason to report offline.

2. 2
   Check the management address

   Hypervisor guests without a guest agent are given a placeholder address that is not routable from OrcaMonitor by design. Install the guest agent to get the real address.

3. 3
   Check reachability from OrcaMonitor

   Not from your laptop. If the route or the tunnel is down, the device is genuinely unreachable from the platform and the fix is connectivity, not the device.

A ticket is sitting in Verifying fix

This state means the change is applied and the objective is being checked. It is a real verification step, not a stalled queue, so it resolves quickly on a healthy remediation.

• Brief stay is normal — the check is running.
• Long stay usually means the objective is ambiguous, or the device stopped answering the verification.
• A long stay after a partial change is intentional: the platform is waiting for a human to decide, and it will not keep acting on its own.

Outbound mail is not arriving

1. 1
   Check the sender address against the relay policy

   This is the most common cause. A relay that does not allow your From domain will reject the message, and the rejection is in the delivery status.

2. 2
   Check the delivery status, not the channel

   Per-message status records the reason. "Mail is not arriving" is usually a specific, recorded rejection rather than a silent failure.

3. 3
   Check that SMTP is configured in the right place

   Notification channels reuse the SMTP delivery configuration. If notifications were configured but SMTP was never filled in, the channel has nothing to send through.

The agent says it has no tools for an integration

Tools are advertised only for integrations that are configured. An unconfigured integration is not "broken", it is absent — and an external integration that fails to connect will not raise an error at startup either, so "no error" does not mean "mounted".

• Confirm the integration is configured in Settings and passes its connection test.
• Ask the agent to search the catalog by capability rather than assuming it is missing.
• Remember the advertised list is a budget: a tool can be absent from the listing and still callable by name.

AI work has stopped and nothing is failing

A workspace AI credit cap pauses work instead of failing it. Parked tickets look idle because they are waiting, not because anything broke.

1. 1
   Look for the credit banner

   It appears on every page in the workspace when the cap is reached, and it is the fastest way to tell a pause from a fault.

2. 2
   Check usage against the cap

   The dashboard shows consumption; a cap that has just been reached explains a sudden stop precisely.

3. 3
   Wait for credits, do not re-run

   Parked work resumes automatically once credits are available. Re-queuing manually risks a duplicate run on the same ticket.

A settings page is missing for one user but not another

Almost always a permission rather than a bug. Page access is granted by a permission row, and a role that has broad settings access does not automatically gain a newly added settings page.

• Superusers see everything, so testing with a superuser account hides this class of problem entirely.
• Verify with a non-superuser who holds the role in question.
• Grant the specific settings page permission to the role — do not widen the role to fix one page.

An update failed and a container is unhealthy

1. 1
   Check free disk space first

   A full disk presents as a service that will not start, which reads like a bad release and is not. Updates prune unused images for exactly this reason.

2. 2
   Check dependency order in the logs

   The database and pooler must be up before the application. An application failure citing the dependency is the dependency failing, not the application.

3. 3
   Check that the agent updated itself

   The agent is upgraded before the release is applied, so an older agent cannot misread newer steps. If the version did not move, the update did not really start.

Inventory does not match the source system

Sync is directional and periodic, so a change in the source appears on the next pass rather than immediately. Deletions are the case worth understanding: an asset removed at the source is removed here, but a device that has configuration backups or security findings attached is protected and reported rather than deleted automatically.

Getting help

When you contact support, send the instance, the ticket or device id, and the timestamp. For agent behaviour, the ticket timeline plus the audit trail answers most questions before anyone needs to reproduce anything.