Troubleshooting

A Vertex request can fail at two points:

• Right away, when Vertex refuses it: the API answers with an RFC 7807 problem and a code (Refused requests).
• Later, when the operation runs: the operation ends failed (or timeout, cancelled) with an error_code and an error message (Failed operations).

Refused requests

Code	HTTP	Meaning and what to do
not_configured	409	No connector or AD account is set for the tenant. Save the directory settings.
connector_unavailable	409	Saving the settings: the chosen connector does not exist (any more) or cannot run Vertex jobs. Choose a connector on a domain controller with a current version (Setting up the domain controller).
writes_disabled	409	This kind of change (users, groups, OUs, GPOs, password policies) is switched off in the directory settings.
deletes_disabled	409	Deletes are switched off in the directory settings.
out_of_scope	403	The object, or the target OU, is outside the managed OUs. Vertex only changes objects below them.
protected	403	The object is privileged or built-in (adminCount=1, a critical system object, a built-in account or group), or one of the default domain policies. Vertex never changes it; do it on the domain controller if it must be done.
forbidden	403	Your role does not allow this, for example a helpdesk user changing a non-contact attribute (Roles).
rate_limited	429	More than 600 changes by you or 2,000 in the tenant in the last minute. Wait a minute.
step_up_required	403	The action needs a step-up: confirm your password on the Hub and send the token.
step_up_unavailable	503	Step-up confirmation is not available on this server.
sync_running	409	A directory sync is already running.
operation_finished	409	Cancelling an operation that has already finished.
import_not_validated	409	The import is not waiting for a commit: it was committed, cancelled, or uploaded more than 24 hours ago.
axis_unavailable	503	Vertex could not reach Entrosity Axis to queue the job; the operation is recorded as failed with this code. Try again; if it persists, see Running Entrosity Vertex.
not_found	404	The object, GPO, import or operation does not exist in the tenant (or not in the mirror yet: run a sync).
validation, invalid_request	422	The request is not valid; detail or fields say which value.

Settings validation (422)

invalid_username (ad_username must be DOMAIN\name or name@domain), invalid_server, invalid_managed_ou (not a DN, or more than 100), invalid_default_ou (not a managed OU or below one), invalid_upn_suffix, invalid_attribute, invalid_interval (5 to 1,440 minutes), invalid_password, password_required (the first save needs the AD password).

Import validation (422)

invalid_mode, invalid_csv (no header row, or a line that cannot be read; the detail names the line), empty_csv, too_many_rows (more than 10,000), unknown_columns, duplicate_column, missing_column (no sAMAccountName), invalid_column (an attr: column that is not allowed). Problems of single rows do not stop the upload; they make the row invalid (Bulk import → Preview).

Failed operations

These are the error_code values of failed operations. Most come from the connector or the PowerShell script on the domain controller; the error message has the details (for AD errors, Windows' own message).

The connector's guard

Code	Meaning and what to do
guard_pending	A local administrator of the domain controller has not accepted Vertex yet, or the managed OUs changed and the new list waits for acceptance, or the guard file is not trusted. Run rmm-connector vertex guard show and accept on the domain controller; accept --ou must name exactly the managed OUs in Vertex's settings (The local guard).
guard_denied	The kind of change (gpo, pso, …) or deletes are switched off in the local guard: rmm-connector vertex guard set --gpo on (or --pso, --deletes, …).
rate_limited	The connector's local cap of writes per minute (default 1,000) is reached, usually by several imports or large membership changes within a minute. Wait a minute and retry, or raise the cap (up to 2,000) with vertex guard set --max-writes-per-minute N (The write cap).
expired	The job reached the connector after its expiry (the connector was offline for an hour, six for imports). Nothing was changed. Send it again.

Checks on the domain controller

Code	Meaning and what to do
out_of_scope	The script found the object (or target) outside the managed OUs, for example because it was moved since the last sync, or a password policy outside the Password Settings Container.
protected	The object, a member to add, or the GPO is protected.
denied_attribute	An attribute on the deny list.
invalid_payload	The request does not fit the object, for example the object is a group but was addressed as a user, or a password is missing.

Access and setup

Code	Meaning and what to do
logon_failed	The AD account's user name or password was refused (wrong password, account disabled, locked out or expired). Correct it in the directory settings.
access_denied	The AD account lacks a right. If the message says may not open a PowerShell session on the domain controller (add it to Remote Management Users), add the account to Remote Management Users (Setting up). Otherwise Active Directory refused the change itself: delegate the right on the OU, the GPO or the Password Settings Container. A live read of the object shows which attributes the account may write.
missing_module	The ActiveDirectory or GroupPolicy PowerShell module is not installed on the domain controller (PowerShell and its modules).
unauthorized	Vertex refused to hand the job its secrets; nothing was changed. The message says why: author_revoked (the author no longer holds the right: their role was changed or they were deactivated after the request), writes_disabled / deletes_disabled (the switch was turned off meanwhile), expired (the operation expired), secrets_used (the job asked twice), or the operation is no longer live (cancelled, or the tenant now uses another connector).
unsupported	The connector cannot run Vertex jobs (not a Windows build) or does not know the operation (update the connector).

Directory errors

Code	Meaning and what to do
not_found	The object, a group or a member does not exist (any more). Run a sync.
already_exists	An object with this name or logon name already exists.
password_policy	The password does not meet the domain's (or the user's fine-grained) password policy: length, complexity, history or minimum age.
ad_error	Any other error of Active Directory or PowerShell; the message is Windows' own. Also used when the script's results could not be delivered.

Operations that did not run

Code	Meaning
timeout	The operation did not finish in time (10 minutes for a change, 30 for a read, an hour for an import batch), or Axis did not answer for an hour after its expiry. Check the result in the directory (a live read) before trying again.
cancelled	Cancelled by a user.
not_dispatched	The job was never handed to Axis.
job_lost	Axis no longer knows the job.

Common situations

Everything fails with guard_pending

The guard has not been accepted, the OUs accepted with --ou are not exactly the managed OUs in Vertex's settings, or the managed OUs were changed in Vertex. Compare rmm-connector vertex guard show with the settings. See Changed managed OUs.

The test fails with access_denied

The AD account is not in Remote Management Users, or WinRM is off on the domain controller (Setting up the domain controller).

Objects are missing or out of date

Lists come from the mirror. Run a sync, or a live read of one object. A sync that failed shows last_sync_status and last_sync_error in the settings.

A user cannot be changed although it is in a managed OU

It is protected: it is (or was) a member of an administrative group (adminCount=1), or a built-in account.

Where to look

• The operation (GET …/operations/{operationID}): error_code, error, the requested params (never passwords) and the result.
• The tenant's audit log: every change and settings change, with its author.
• On the domain controller: rmm-connector vertex guard show, and the connector's log %ProgramData%\RMM Connector\logs\connector.log.
• The Axis job of the operation in Axis (the connector's jobs).