Documentation
Troubleshooting
Find the cause of a sign-in message, a failed scan, a quiet agent, a failing webhook or an import with errors, and the step that resolves it.
This page collects the messages and symptoms you are most likely to meet, grouped by area. Each entry tells you what you see, the likely cause, and what to do. The linked pages explain each screen in full.
Sign-in problems
When sign-in fails, a red message appears above the Sign in form. Find it in the table below. For the full sign-in flow, see Signing in.
| What you see | Likely cause | What to do |
|---|---|---|
| That email and password don’t match. Check your details and try again. | The email or password is wrong, or a field is empty. | Check both fields; click the eye icon to see the password you typed. If you have forgotten it, click Forgot password? (see Reset a forgotten password). |
| Caps Lock is on. | Caps Lock is active while you type your password. | Turn Caps Lock off unless your password is in capitals. |
| Too many sign-in attempts. Wait a moment and try again. | After 5 failed attempts within 5 minutes, the account is locked for 15 minutes (see Account lockout). | Wait 15 minutes, then sign in with the correct password. A successful sign-in resets the count. |
| This account is deactivated. Contact your administrator. | An administrator has deactivated your account. | Ask your administrator to reactivate it. |
| Something went wrong on our end. Please try again in a moment. | DeviceQuest had a temporary internal error. | Try again in a moment. If the message returns, contact your administrator. |
| Could not reach the server. Check your connection and try again. | The connection between your browser and DeviceQuest dropped. | Check your network connection or VPN, then try again. |
| Could not sign you in. Check your details and try again. | Another sign-in problem. | Check your details and try again. |
| Invalid code. Try again. on Enter your code | The authenticator code is wrong or has already rolled over. | Type the next code from your app, and check that your phone’s clock is set automatically. See Code messages. |
| That backup code is not valid or has already been used. | The backup code is mistyped or already used; each backup code works once. | Try another backup code. If your phone is gone, see If you lose your phone. |
| Invitation no longer valid or Invitation not found | The invitation link is older than 7 days, was already used, was revoked, or was copied incompletely. | Copy the full link from the email, or ask your administrator to send a new invitation. See Invitation messages. |
| reset link is invalid or expired | The password reset link is older than 24 hours or was already used. | Ask your administrator for a new link. See Reset messages. |
DeviceQuest asks you to sign in again. A session lasts one hour, and setting a new password ends your other sessions. Sign in again to continue; see How long you stay signed in.
Single sign-on does not continue. Continue with SSO needs the exact ORGANIZATION ID your administrator gave you. Check it for typing errors, then try again. Administrators find the identifier on the SSO (SAML) page in the Administration section.
Access restricted
What you see: Access restricted instead of the page, with a message that names the area, for example You don’t have permission to view assets. Contact an admin if you think this is a mistake.
Likely cause: your role does not include the permission that the page needs. Every documentation page lists its permissions at the top, and some pages accept any one of several permissions (for example, Developer opens with webhooks:read or api_keys:read).
What to do:
- Note the page you tried to open and the area in the message.
- Ask your administrator for a role that includes the permission listed at the top of that page’s documentation. Administrators manage roles on the Roles and permissions page in the Administration section.
- If you need to use a different account, click Sign out on the Access restricted screen and sign in again. Otherwise, click Back to dashboard.
See Access restricted.
Scan errors
A failed scan on the Results tab of Scanning shows an error category with a code. Hover over the category to read the error message, or click View to open Scan result, which shows the category, the code, the suggested next step and the Scan log. After you fix the cause, click Retry. See Scan results.
| Category | Likely cause | What to do |
|---|---|---|
Auth failed (SCAN_AUTH_FAILED) | The target rejected the login: the username, password or SSH key in the credential does not match this target. | Check the credential on the Credentials tab, or assign the asset its own default credential. Then retry. |
Unreachable (SCAN_HOST_UNREACHABLE) | The scanner has no route to the host, or a firewall blocks it. | Check the target address, the network route and the firewall rules between the scanner and the target. For a remote network, run the scan through a bridge host agent. |
Timeout (SCAN_TIMEOUT) | The target did not answer in time. | Confirm the target is online and reachable. For slow networks, raise the timeout in a scan profile and attach it to the schedule. Then retry. |
Agent timeout (SCAN_AGENT_TIMEOUT) | The bridge host agent did not acknowledge the scan command in time. | Check that the agent is running and online (see Agent not reporting), and that its heartbeat interval is 60 seconds or less (the default is 30 seconds). |
No permission (SCAN_PERMISSION_DENIED) | The login worked, but the account lacks the privileges the scan needs on the target. | Give the scan account the privileges the scan type needs, or use a credential for an account that has them. See Scan types. |
No credential (SCAN_CREDENTIAL_MISSING) | The scan type needs a credential, and none is set on the schedule or the asset. | Assign a credential to the schedule, or a default credential to the asset, then retry. See Which credential a scan uses. |
Invalid target (SCAN_INVALID_TARGET) | The target and the scan type do not fit together, for example a CIDR range with an SSH scan. | Use Sweep for CIDR ranges, and a single host for SSH, WMI or SNMP. See Scan targets. |
Protocol error (SCAN_PROTOCOL_ERROR) | The service on the port answered with something other than the expected protocol. | Check that the right service listens on the port, and set the port in a scan profile if it differs from the default. |
Internal error (SCAN_INTERNAL) | Another problem stopped the scan. | Open View and read the error message and Scan log; they name the step that stopped. Retry the scan. |
Stalled (SCAN_ORPHANED) | The scan ran longer than its maximum runtime, or its worker stopped without reporting, so DeviceQuest marked it failed. | Retry the scan. If it stalls again, ask your DeviceQuest operator to check the control plane’s health. |
A sweep shows Completed with issues. The sweep itself finished, and some per-device follow-up scans failed. Click the Schedule cell to expand the devices, filter by Issues, and fix each device by its category. Click Retry on a device to rescan only that device.
A sweep finds machines but inventories none. Scan result reads No authenticated device scans were launched. Assign a credential to the schedule, or a default credential to the assets, and run the sweep again. See Sweep.
Agent not reporting
Host agents send a heartbeat every 30 seconds. Admin → Host Agents shows an agent as online after a heartbeat in the last 2 minutes and offline after that. See Agent statuses.
The agent shows offline
Likely cause: the agent service stopped, or the host lost its connection to the agent gateway.
What to do:
- On Linux, run
systemctl status devicequest-agentand expectactive (running). On Windows, check that theDeviceQuestAgentservice is running in Services. - Read the log. On Linux, run
sudo journalctl -u devicequest-agent -f. - Check that the host can reach the gateway: port 443 to your DeviceQuest host through a Kubernetes ingress, or port 50051 to the control plane for a direct connection. See How the agent connects and Network requirements.
While an agent is offline, it keeps its results in its offline buffer, and queued commands wait for it. Both are delivered when it checks in again.
A new agent never appears
Likely cause: the agent could not enroll. Each bootstrap credential enrolls exactly one agent and is then used up; it also stops working when it expires or is revoked.
What to do: read the agent log and match the message:
| Message | What to do |
|---|---|
install command not found or expired; ask your admin for a new one | Issue a new bootstrap credential on the Enroll Agent page (Administration section) and copy the new command. |
error: download failed. The install command may have expired or been used; ask your admin for a new one. | Issue a new bootstrap credential and copy the new command. |
enrollment: … | The credential was expired, revoked or already used. Issue a new credential and run the install command again. |
connect to gateway: … | The host cannot reach the gateway. Check DNS, the port and firewalls between the host and the gateway. |
agent gateway not available in on-prem mode | The agent runs without -mode hybrid or -mode saas. Run install again with one of them. |
The full message lists are in Install on Linux, Installer messages for Linux and Installer messages for Windows.
Certificate errors
Likely cause: the gateway’s certificate comes from a private certificate authority that the host does not trust, or the agent connects without TLS through an ingress.
What to do:
- On Linux, tick The server certificate is from a private CA (I have its ca.pem on the host) when you copy the install command, and run it from the directory that holds
ca.pem. See Private certificate authority. - On Windows, import the CA into the computer’s Trusted Root Certification Authorities store, then run the install command again.
- Through a Kubernetes ingress, the agent connects with
-tls. The one-command install sets this for you; for a manual install, add-tlsor-ca-file <path>. See the CLI reference.
The agent was revoked
What you see: the log shows gateway rejected this agent (revoked or token invalid); re-run the install command to re-enroll, and the agent’s status is revoked.
What to do: issue a new bootstrap credential and run the install command again. See Revoke an agent.
Remote deploy times out
What you see: the Deploy monitoring agent dialog stops at agent did not enroll/heartbeat within timeout.
What to do: the agent was installed but did not reach the gateway within 90 seconds. Check that the asset can reach the gateway address, then read journalctl -u devicequest-agent on the asset. See If a deployment fails.
Webhook deliveries failing
A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds. Any other answer, a timeout or a connection error is a failed attempt. DeviceQuest retries with growing delays, up to 10 attempts. Open the webhook’s side sheet on the Developer page and check Recent deliveries for the status, the number of attempts and the last error. See Deliveries.
Deliveries show Failed or Dead letter
Likely cause: your endpoint is down, slow, answers with a non-2xx status, or rejects the signature.
What to do:
- Click Test in the side sheet. Test request delivered successfully to “
”. confirms that the address, TLS and your signature check work. See Send a test delivery. - Read the last error in Recent deliveries, and fix your endpoint so it answers
2xxwithin 10 seconds. Do slow work after you answer, not before. - A Failed delivery is retried automatically, so it arrives once the endpoint is fixed. A Dead letter delivery has used all 10 attempts; click Show payload to see the body it carried. New events deliver normally once your endpoint answers
2xx.
See Retries and failed deliveries.
Your endpoint rejects the signature
Likely cause: the receiver computes the HMAC over re-serialised JSON instead of the raw body, leaves out the X-DeviceQuest-Timestamp value, or uses an old secret.
What to do:
- Compute the HMAC-SHA256 over the raw request body bytes immediately followed by the
X-DeviceQuest-Timestampvalue, keyed with the signing secret as a string, and compare the lowercase hex result withX-DeviceQuest-Signature. - Check your code with the test vector in Verifying signatures.
- After Rotate secret, the old secret stops working at once. Update your receiver with the new secret straight away.
- Keep your server’s clock in sync, so your timestamp check accepts fresh deliveries.
The URL is refused when you save
Likely cause: the URL breaks one of the endpoint URL rules: it carries a user name or password, the host name does not resolve, or it points to a loopback, private or link-local address.
What to do: use a public https:// address without credentials in it. To deliver to a receiver on a private network, ask your DeviceQuest administrator to allow that destination. See Endpoint URL rules.
No deliveries arrive at all
What to do: open the webhook and check that Active is selected and that Event types includes the events you expect. Test requests do not appear in Recent deliveries; only deliveries of real events do.
Imports with errors
Asset Ingestion reports the outcome of every file in the upload panel and in Recent uploads. See Asset ingestion.
| What you see | Likely cause | What to do |
|---|---|---|
| Unsupported file type “.txt”. Allowed: .csv, .json, .xml, .nmap | The file extension is outside the allowed list. | Save the file as .csv, .json, .xml or .nmap. DeviceQuest chooses the parser from the extension. |
| File exceeds the maximum size of 50 MB. | The file is larger than 50 MB. | Split the file into smaller files and import each one. |
| Parsed | Every row parsed, but no row carried an identifier key. | Add one of the identifier keys (hostname, IP address, MAC address, serial number or ARN) to each row, then import again. |
No assets were imported from this file. with reasons such as row 3: missing one of hostname, ip_address, mac_address, serial_number, or arn | The listed rows have no identifier key or could not be read. | Fix the rows named in the reasons and click Try again. |
| Partial in Recent uploads | Some records were ingested and some were skipped. The message under the badge lists the skipped rows. | Fix the skipped rows and import the file again. Rows already imported are updated, not duplicated. |
| Failed in Recent uploads | No records were ingested. The message under the badge explains why. | Correct the file as the message describes and import it again. Check the expected layout in File formats. |
| Failed count above zero in Ingestion queue | Some queued ingestion work needs review. | Click Refresh to update the counts, then check Recent uploads for the failed file and its message. |
| Queue status unavailable. | The queue counts could not be loaded at that moment. | Click Retry. |
“Can’t reach the server”
What you see: a page shows Can’t reach the server with We’re having trouble reaching the server right now. Your session is still active — please try again in a moment. and a Try again button.
Likely cause: the DeviceQuest server is briefly unavailable to your browser, for example while it restarts after an update, or your network connection dropped.
What to do:
- Wait a moment, then click Try again. Try again reloads the page. Your session is still active, so you stay signed in.
- Check your network connection or VPN.
- If the screen stays after a few minutes, contact your DeviceQuest administrator or operator so they can check the server.
Something went wrong with Try again appears when a single page could not load. Click Try again; the rest of DeviceQuest keeps working. See Error screens.