Common issues

​

Agent fails to execute

1. Check binary permissions. The agent’s service user needs execute permission on the binary. On Linux: chmod +x agent-executable.
2. Confirm the API key is set. The agent reads LUUMEN_API_KEY from the environment or luumen.api.key from config.yaml. If neither is set, the agent exits immediately.
3. Confirm network access to the Luumen API. From the Patch server:
   curl -H "api-key: YOUR_API_KEY_HERE" "https://ns2-api.apiphani.io/v2/api/v1/health"
   
   A successful response means network and authentication are both working.
   If curl hangs or returns a network error, the Patch server cannot reach Luumen’s API. This is a network problem (firewall, proxy, DNS) and needs your network team to resolve — it isn’t something Apiphani can fix from our side.
4. Check the logs. Open log/[date]/agent.log from the most recent run. Config errors, authentication errors, and startup failures all surface here.
5. Escalate. If everything above looks correct and the agent still won’t run, contact your Apiphani Account Manager with the latest logs.

​

Agent cannot connect to hosts

1. Confirm credentials are configured. Open the Hosts area in the UI and check that each affected host either uses default credentials (and the default is set) or has its own per-host credentials.
2. Test credentials manually from the Patch server. Try a direct SSH or WinRM session using the same user, key, or password configured in the UI. If the manual session fails, fix the credential at the source (key permissions, password value, allowed users) before suspecting the agent.
3. Check for problematic characters in passwords. Passwords with backticks, dollar signs, or unescaped quotes can break connection strings. Either escape them or rotate to a simpler password.
4. Escalate. If a manual session succeeds but the agent still fails, contact your account team with the agent log for that host (log/[date]/checks/[host_ip].log).

​

Missing properties on a host

1. Open the per-host log on the Patch server: log/[date]/checks/[host_ip].log.
2. Search for the property name. Use partial or fuzzy search — the agent’s internal property names are close to but not always identical to the UI labels. For example, SAP Components in the UI corresponds to sap_components in the log.
3. Verify the underlying command or query worked. The log shows the raw OS command (or OData call) and its response. If the response is empty or an error, that’s the root cause — typically a permissions issue on the target host.
4. Verify the property was reported to Luumen. Open log/[date]/agent.log and look for the API call for the host. The payload should include the property. If the agent collected the property but it’s missing from the UI, that’s a Luumen-side issue.
5. Escalate. If the property is collected and submitted but not visible, contact your account team.

​

All hosts disconnected

1. No assigned checks. Hosts that don’t belong to any group, or whose groups have no checks assigned, appear disconnected because there’s nothing to evaluate. If you’re a brand-new client, you likely need to create groups and assign initial checks. See Host groups and Creating checks.
2. Stale data. If the agent hasn’t run recently (service stopped, network down), the dashboard reflects the last successful run. Once the agent runs again, status updates.
3. Escalate. If you’ve assigned checks and confirmed the agent has run, contact your account team.

​

I created a new check, but it’s not showing up

• Wait for the next agent run. Check evaluation happens during the agent run, not at save time. For an hourly schedule that means a worst case of about an hour. Trigger a manual run from the Patch server if you don’t want to wait — see Scheduling runs.

​

I do not see any unresolved SAP Security Notes, but expect to

1. Confirm SAP Components is collected. The matching engine uses the SAP Components property. If your hosts don’t have it, no notes can match. Open an SAP host’s detail page and confirm the property is present.
2. Check the agent log for the SAP components call. In log/[date]/checks/[host_ip].log, look for the OData call that retrieves SAP Components. If you want, run the same call manually with curl from the Patch server to confirm the upstream returns data.
3. Confirm the agent submitted the data. Open log/[date]/agent.log and confirm the call for the host includes SAP components.
4. Escalate. If components are collected and submitted but no notes match, contact your account team.

​

I do not see any unresolved Vulnerabilities, but expect to

1. Confirm OS Packages and/or Python Packages are collected. Without one of these, no CVEs can match.
2. Check the agent log for the package enumeration command. In log/[date]/checks/[host_ip].log, look for the call that lists installed packages (rpm -qa, dpkg -l, pip list, etc.).
3. Confirm the agent submitted the data. Open log/[date]/agent.log and confirm the call for the host includes packages.
4. Escalate. If packages are collected and submitted but no CVEs match, contact your account team.

​

Need more help?