Skip to content

Integration errors and what they mean

Support-facing. The failures that actually get raised, what each one is telling you, and what to do about it. Ordered roughly by how often they come up.

Connection and credentials

"Authentication failed" immediately after saving

The credentials are wrong, or they are right and the account lacks API access. These are different problems with the same message, and the distinction matters: a security team will often issue a console login and assume it works for the API.

Check, in this order:

  1. Is the account's API access enabled in the tool, separately from console access?
  2. Is the API URL the right one for your region or instance? Several vendors use region-specific endpoints, and a wrong region authenticates as a wrong password.
  3. Has the credential expired or rotated since it was entered?

The connection test passes but no data arrives

Authentication and authorisation are separate. The account can sign in; it cannot see the scans. In most tools, API accounts see only the scans, asset groups or projects they have been explicitly granted.

This is the most common integration ticket, and it is almost never an NxSAM problem. Ask the tool's administrator what the API account can see — not what your own account can see.

It worked for months and then stopped

In order of likelihood: the credential expired or was rotated; the account was disabled during a review; a network path changed (a new firewall rule, a proxy, an IP allow-list that no longer includes NxSAM); or the tool's API version was deprecated.

The last sync timestamp tells you when it stopped, which usually identifies the change.

Import and parsing

Rows rejected during staging

Almost always one of:

  • Column mapping. The report has a column the mapping does not expect, or the tool changed its export format in an upgrade. Re-check the mapping against a current export rather than against the documentation.
  • Date format. The mapping specifies how dates are written in the file. A file produced with different locale settings will parse dates wrongly, or not at all — and wrongly is worse, because 03/04/2026 is valid in two formats that are five weeks apart.
  • A required field is empty. Some rows in an otherwise valid export genuinely lack the field NxSAM matches on.

The per-row rejection reason is recorded. Read it before theorising.

The import completed but the numbers are lower than the source

Expected when part of the file was rejected. Compare the source row count against the imported count plus the failed count. If those reconcile, nothing was lost silently.

If they do not reconcile, the difference is deduplication: the same finding appearing twice in one file is imported once.

Findings landed against the wrong asset

The identifier in the file matched a different asset than intended. Hostname-based matching is the usual culprit — short name against fully-qualified name, or two hosts sharing a name in different environments.

This is a matching-configuration question, not an import failure, and correcting it retrospectively means re-importing after fixing the identifier.

Queue and worker

Status stuck at PENDING

The message was queued and nothing consumed it. Either no worker is running for that queue, or the broker is unreachable.

Every module's imports, scheduled reports and outbound email share this infrastructure, so if this is the cause you will see all three stalled together. That correlation is the quickest way to confirm it.

Status stuck at IN PROGRESS

A worker took the message and did not finish. Usually the worker process died — a restart, an out-of-memory kill on a very large file, or a container replacement mid-job.

Unlike a failure, this does not release the message cleanly, so the job neither completes nor retries.

Status FAILED

The worker ran and raised an error. The task detail carries the reason. Common causes are a malformed file that passed staging, and a referenced asset or audit that no longer exists because it was deleted while the job was queued.

Partially completed

Specific to tool sync. Some assets in the batch synced and others did not — commonly because the API account can see some asset groups and not others, or because a subset of hosts timed out. It will not retry on its own.

Configuration

matTabContent / a blank integration screen

Three integration screens (Checkmarx, Checkmarx SCA and Fortify) log a template binding error on load. The tabs still work. This is a known product defect, recorded in the project's findings log; it is not a symptom of a broken integration.

An icon fails to load and the screen does not render

Reported on RLCM Controls and Templates. An icon is registered with a filename whose case does not match the file on disk, which resolves on Windows and 404s on Linux. Also a known defect rather than a configuration problem.

What to collect before escalating

  • The integration and the tool version
  • The last successful sync timestamp
  • The queue status and the task detail for the failing job
  • The failed-row reasons, if the job reached staging
  • Whether other queues (reports, email) are also stalled

Those five answers resolve or correctly route almost every integration ticket, and the last one in particular distinguishes an integration problem from an infrastructure one.