Error scenarios and what they actually mean¶
Messages a user is likely to report, what causes each, and what to check. Message text is taken from the application code; wording may differ slightly by version.
Upload and import¶
"A scan is scheduled, so cannot initiate new scan / upload."¶
Cause. A scan is already queued or running for this audit. The platform refuses a second concurrent upload rather than interleaving two result sets, which would corrupt matching.
Check. Look at the scan or upload queue for that audit. Either it is genuinely running, or a previous run failed without clearing its state.
Resolution. Wait for the running job, or clear the stalled one. Do not work around it by creating a second audit — that splits the finding history for the same asset.
"Audit Document can not be uploaded for the current audit status"¶
Cause. The audit is in a status that does not accept documents. Uploads are gated by audit status by design, so evidence cannot be added to an audit that has been completed or aborted.
Check. The audit's current status.
Resolution. Move the audit to a status that accepts uploads, or attach the evidence to the correct audit. If the audit was closed prematurely, reopening it is the honest fix — attaching evidence elsewhere makes the record misleading.
Missing mandatory columns¶
Cause. The import validates that required headers are present before processing, and
rejects the file outright if any are missing. For Qualys imports the plugin identifier
(qid) is one of them.
Check. Open the file and compare its header row against the expected columns. The usual causes are an export template change, a different export format from the same tool, or a file edited in a spreadsheet that dropped or renamed a column.
Resolution. Re-export using the correct template. Do not hand-add a missing column with invented values — see the vulnerability-key behaviour in the integrations reference; a fabricated key part silently changes what matches what.
Unmapped assets in an upload¶
Cause. The file references hosts or applications that do not exist in NxSAM, or that exist under a different identifier.
Check. Whether the assets exist at all, and whether the identifier in the file matches the identifier NxSAM holds — an IP against a hostname, a URL with a trailing slash, a different case.
Resolution. Create or correct the assets first, then re-upload. Findings for unmapped assets are not silently discarded, but they cannot be filed correctly until the asset exists.
"Duplicate severities" / "Duplicate control name in file"¶
Cause. The uploaded file contains the same key twice. The import refuses rather than guessing which row wins.
Check. The file itself, not NxSAM. Duplicates usually arrive from concatenating exports or from a spreadsheet copy.
Resolution. De-duplicate the file. Which duplicate is correct is a judgement the platform should not make on the customer's behalf.
Reports and background work¶
"Unable to connect with Queue server"¶
Cause. The message broker is unreachable. Report generation, imports and several status transitions publish to a queue; without it they cannot be accepted.
Check. Whether the broker is running, and whether the application server can reach it.
Resolution. Restart or restore the broker. Note that anything submitted while it was down was refused rather than queued — those requests need resubmitting; they will not drain automatically.
This error is not about the report
Users report it as "my report failed". Nothing is wrong with the report or the data — the request could not be accepted. Regenerating once the broker is healthy is all that is required.
A report never arrives¶
Cause. Usually queued behind other work rather than failed.
Check. Process Manager, to see whether the job is queued, running, or errored.
Resolution. If queued, wait. If errored, the error is on the job. If absent entirely, the submission never reached the queue — see the broker error above.
Integrations¶
"Unable to connect to "¶
Cause. The endpoint is unreachable, credentials are rejected, or a proxy is required and not configured.
Check, in this order:
- Can the NxSAM server reach the endpoint at all? Network before credentials.
- Are the credentials valid, and is the account API-enabled rather than interactive-only?
- Does this deployment need a proxy for outbound traffic?
Connects successfully, imports nothing¶
Not an error message, and the most commonly misdiagnosed condition. The connection is fine and the account simply cannot see anything in scope.
Check. What the service account can see in the source tool, signing in as that account. Almost always the account exists and authenticates but was never granted access to the target scope.
Access and permissions¶
"Permission denied" / a module missing from the sidebar¶
Cause. Two different mechanisms, and they need distinguishing before anything is changed:
| Symptom | Mechanism | Fix |
|---|---|---|
| Module absent from the sidebar | Role does not include it | Role change |
| Module present but empty | No assets owned or assigned | Ownership or mapping change |
Check. Whether the user can reach the screen at all. That single question separates the two.
Permissions are resolved at sign-in
A permission change may not take effect until the user signs out and back in. Before escalating "the permission change did not work", have them re-authenticate.
"Invalid credentials" at sign-in¶
Cause. Wrong password, a locked account, or — where corporate sign-on is configured — a directory problem rather than an NxSAM one.
Check. Whether the deployment uses directory authentication. If it does, NxSAM does not hold the password at all and the investigation belongs with the directory.
Deviations¶
"Invalid deviation request" / "Invalid number of approver levels"¶
Cause. The request does not satisfy the configured approval workflow — commonly a required field is absent, or the approval configuration expects a number of levels that the request does not provide.
Check. The approval configuration for the severity in question, and whether it was changed after the request was raised. Routing is fixed at request time, so a request raised under an older configuration can conflict with a newer one.
A general principle¶
Most NxSAM errors are refusals rather than faults: the platform declines an operation that would produce inconsistent data. Before treating a message as a defect, establish what it was protecting against. "Cannot upload while a scan is running" is not a limitation to be worked around — it is preventing two result sets from being interleaved.