Error codes

Codes are stable identifiers: clients and scripts may match on them.

Portal API problem codes

Returned in the code field of application/problem+json (Portal API → Errors).

General

Code	HTTP	Meaning
validation	422	Request body or parameters failed validation; fields names each problem.
malformed_body, body_too_large	400	Unreadable JSON, or larger than 1 MB.
unauthenticated	401	No or invalid access token (see Sign-in and tenants).
forbidden	403	Your role lacks the permission.
no_access_rule	403	The route has no access rule (a server bug; every route must have one).
rate_limited	429	Too many requests from your IP address.
not_found	404	Not found, including resources of another tenant.

Sign-in and tenants

Axis signs nobody in: sign-in, password, two-factor, invitation and user-management errors come from the Hub (Entrosity Hub problem codes). Axis answers unauthenticated (401) when the Hub's product token is missing, invalid or expired, its session was ended on the Hub, or the user is unknown to Axis, disabled, or has no active tenant left.

Code	HTTP	Meaning
site_name_taken	409	The site name is in use in this tenant.

Deleting an enrollment token needs a step-up token from the Hub: a missing, expired, reused or foreign step_up_token is a validation error on step_up_token (confirm the password again).

Packages, deployments and scripts

Code	HTTP	Meaning
package_not_ready	422	The package file has not been uploaded and verified.
package_ready	409	The file of a ready package cannot be replaced.
package_has_no_file	409	Winget packages have no file to upload.
package_in_use	409	Used by an unfinished deployment.
package_read_only	403	Global packages can only be changed by global admins.
upload_missing, size_mismatch, hash_mismatch, object_key_mismatch	422	The uploaded file is missing or does not match what was declared.
storage_unavailable	503 / 409	Object storage is not configured.
winget_index_unavailable	503	The winget index has not been loaded (or RMM_WINGET_SOURCE_URL=off).
no_targets	422	The selection contains no device with an agent.
too_many_targets	422	More than 20,000 targets.
invalid_state	409	The deployment cannot be paused/resumed/cancelled in its state.
not_applicable	422	Add new devices on a deployment to an explicit list.
target_not_retryable	409	Only failed, timed-out or cancelled targets can be retried.
run_finished, job_finished	409	The script run or job already finished.

Devices, AD and alerts

Code	HTTP	Meaning
both_have_agents	409	Merge refused: both records have an agent.
connector_offline	409	The connector is offline.
connector_timeout	503	The connector did not answer in time (LDAP test, OU list).
invalid_connector_result	503	The connector returned no or an invalid result.
run_in_progress	409	An AD sync run is already active for this configuration.
push_credential_required	422	The AD configuration has no push account.
invalid_ldap, invalid_ca_pem, invalid_ou, invalid_interval	422	Invalid AD configuration.
global_rule	403	Tenants cannot edit global alert rules (only switch them off).
offline	409	Remote desktop: the device is offline.
no_agent, decommissioned	409	Remote desktop: the device has no agent, or is decommissioned.
remote_unsupported	409	Remote desktop: the agent does not announce remote_desktop (not Windows, or older than this release).
remote_busy	409	Screen wall: someone is in a remote desktop session with the device; a wall never replaces it (tile In a remote session).
remote_wall_unsupported	409	Screen wall: the agent does not announce remote_wall (tile Agent update needed).
screen_wall_unavailable	503	Screen wall: Entrosity Matrix is not configured (RMM_MATRIX_INTERNAL_URL).
remote_unattended_forbidden	403	Remote desktop without the permission prompt or without the session bar needs devices:remote_unattended (tenant and global admins).
remote_session_ended	410	The agent tried to join a remote desktop session that is no longer pending.
remote_session_taken	409	The agent already joined this remote desktop session.
relay_forbidden	403	Replica-to-replica relay with a missing or invalid token.

Releases

Code	HTTP	Meaning
release_exists	409	This version is already released.
not_draft	409	The release is already published.
upload_missing, upload_mismatch	409	The MSI is missing or does not match the declared size and SHA-256.
signing_key_missing	409	RMM_RELEASE_SIGNING_KEY is not configured.

Entrosity Hub problem codes

Answers of the Hub's API (Hub API); validation, unauthenticated, forbidden, not_found, rate_limited and no_access_rule mean the same as above.

Code	HTTP	Meaning
invalid_credentials	401	Wrong e-mail or password.
totp_required	403	Two-factor authentication is on; send totp_code.
totp_invalid	401	Wrong or reused authenticator or recovery code.
account_locked	429	Too many failed sign-ins; try again later.
invalid_session	401	The session cookie is missing, expired, revoked or reused; sign in again.
cross_site_request	403	A session-cookie request that did not come from the Hub's own pages.
no_product_access	403	Product token asked for a product the user has no role in.
totp_setup_required	403	Product token refused: an organization of the user requires two-factor authentication, which is not set up.
totp_required_by_organization	409	Two-factor authentication cannot be turned off while an organization requires it.
totp_enabled, totp_not_enabled, totp_not_pending	409	Two-factor setup in the wrong state.
invalid_token	400	Invitation or reset link is invalid, used or expired.
sign_in_required	409	The invited address already has an account: sign in, then accept.
invitation_other_account	409	Signed in as someone else than the invited address.
already_member, already_platform_admin	409	The invitation would grant nothing new.
email_taken	409	A user with this e-mail address exists.
slug_taken	409	Another organization uses the slug.
organization_suspended	409	The organization is suspended.
last_org_admin	409	An organization must keep one active admin.
last_platform_admin	409	The Hub must keep one active platform admin.
self_change	409	You cannot disable, delete or demote yourself.
self_reset	409	You cannot reset your own authentication; use your account page.
user_not_active	409	A password reset by a platform admin needs an active user.
nothing_to_reset	409	Two-factor reset asked for a user without two-factor authentication.
bootstrap_done	409	bootstrap-admin ran after a platform admin already exists.

Entrosity Edge codes

Edge problem codes

Answers of Edge's API (Edge API) and connector API. Sign-in problems come from the Hub (above).

Code	HTTP	Meaning
validation	422	The body or parameters failed validation; fields names each problem.
malformed_body, body_too_large	400	Unreadable JSON, or larger than allowed (1 MB; connector event chunks 4 MiB).
unauthenticated	401	No, invalid or expired Hub product token, the Hub session ended, or the user is unknown to Edge or disabled.
forbidden	403	Your role lacks the permission.
no_access_rule	403	The route has no access rule (a server bug).
not_found	404	Not found, including resources of another tenant. The detail names the resource (controller not found).
(no code)	429	Too many API requests from your IP address.
site_name_taken	409	A site with this name exists in the tenant.
name_taken	409	A schedule or access group with this name exists in the tenant.
holiday_exists	409	There already is a holiday on that date.
schedule_in_use	409	The schedule is used by access groups and cannot be deleted.
card_already_registered	409	A card with this facility code and number (or iButton id) is registered in the tenant.
controller_address_taken	409	Another controller of this connector uses this address (and bus address).
door_in_use	409	A new doors layout would remove door 2 while access groups use it; the detail (and fields.door_mode) names the groups. Remove the door from them first.
connector_offline	409	The connector is offline: discovery and remote door opening need it online.
controller_disabled	409	The controller is disabled: opening its doors, testing it and sending its configuration again are refused. Enable it first.
connector_has_controllers	409	A connector that still drives controllers cannot be removed.
job_finished	409	The connector reported on a job that has already finished.
enrollment_token_invalid	401	Unknown enrollment token, or not an Edge connector token.
enrollment_token_exhausted	409	The token has no uses left.
enrollment_token_expired	410	The token expired or was revoked.
rate_limited	429	Too many connector enrollments from this IP address.
invalid_request	422	The enrollment request is invalid.
connector_unauthorized	401	The connector key is unknown or revoked (connector removed, tenant suspended).
invalid_message	422	A connector message or HTTP fallback body failed validation.
master_key_missing	409	EDGE_MASTER_KEY is not set on the server: controller PINs cannot be set or cleared (controller PINs need EDGE_MASTER_KEY on the server), and connector releases cannot be published.
download_link_invalid	403	A connector release download link is expired, altered or signed with another key.
release_exists	409	Publishing a connector release: this version is already released with a different MSI (the same MSI again answers 200).
signing_key_missing	409	Publishing a connector release: EDGE_RELEASE_SIGNING_KEY is not set, so releases cannot be signed.

Deleting an enrollment token needs a step-up token from the Hub; a missing, expired, reused or foreign step_up_token is a validation error on step_up_token.

Controller sync codes

Shown with a controller whose Configuration is Failed (Configuration sync and troubleshooting):

Code	Meaning
controller_capacity_exceeded	More cards have access through the controller than it holds (2,000); nothing was sent.
too_many_schedules	The controller's doors use more than 255 schedules; nothing was sent.
connector_removed	The controller's connector was removed.
timeout	The connector did not apply the configuration in time.
controller_pin_unavailable	Edge cannot decrypt the controller's stored PIN (EDGE_MASTER_KEY lost or changed); nothing was sent. Set the PIN again.
Edge job error codes (below)	The connector reported the failure.

Edge job error codes

Reported by the Edge connector in job.result.error_code (Edge connector protocol):

Code	Meaning
capacity_exceeded	The configuration has more cards than the controller holds.
controller_unreachable	The controller did not answer.
config_rejected	The controller, or the connector's check, refused the configuration.
unsupported	The driver cannot do this yet (TrackBase002 beyond the connection check).
unknown_driver	The connector has no driver of that name.
invalid_payload	The job payload is invalid.
exec_failed	The connector restarted before the job finished, or (self-update) the update could not be scheduled.
update_unsigned	Self-update: the connector build has no release public key and refuses updates.
signature_invalid	Self-update: a release signature did not verify.
download_failed, hash_mismatch	Self-update: the MSI could not be downloaded, or does not match the release.

Entrosity Sphere codes

Sphere problem codes

Answers of Sphere's API (Sphere API) and connector API. Sign-in problems come from the Hub (above).

Code	HTTP	Meaning
validation	422	The body or parameters failed validation; fields names each problem (for example a playback longer than 24 hours, a recording search longer than 7 days, an unknown time zone, a layout other than 1, 4, 6, 8, 9, 16, 25, 36 or 64, a release version that is not a semantic version).
malformed_body, body_too_large	400	Unreadable JSON, or larger than allowed (1 MB; connector alarm chunks 4 MiB).
unauthenticated	401	No, invalid or expired Hub product token, the Hub session ended, or the user is unknown to Sphere or disabled.
forbidden	403	Your role lacks the permission, including playback without playback:view and shared views without views:manage.
no_access_rule	403	The route has no access rule (a server bug).
not_found	404	Not found, including resources of another tenant, another user's viewer session or saved view. The detail names the resource (nvr not found).
(no code)	429	Too many API requests from your IP address.
site_name_taken	409	A site with this name exists in the tenant.
nvr_address_taken	409	The connector already drives an NVR at this host and port.
nvr_offline	409	The NVR is disconnected or not online (also while its connector is offline): no video, PTZ or recording search. Optimising an NVR for live view needs it connected.
camera_disabled	409	The camera is switched off.
stream_limit	409	Too many streams for the connector, or main streams or playbacks for the NVR (Limits).
connector_offline	409	The connector is offline: testing an NVR or optimising it for live view needs it online.
connector_has_nvrs	409	A connector that still drives NVRs cannot be removed.
job_finished	409	The connector reported on a job that has already finished.
enrollment_token_invalid	401	Unknown enrollment token, not a Sphere connector token, or its tenant is suspended.
enrollment_token_exhausted	409	The token has no uses left.
enrollment_token_expired	410	The token expired or was revoked.
rate_limited	429	Too many connector enrollments from this IP address.
invalid_request	422	The enrollment request is invalid.
connector_unauthorized	401	The connector key is unknown or revoked (connector removed, tenant suspended).
invalid_message	422	A connector message or HTTP fallback body failed validation.
unauthorized	401	Uploading a connector release: wrong or missing release token, or SPHERE_RELEASE_TOKEN is not set.
release_exists	409	Uploading a connector release: this version is already published.
releases_disabled	503	Uploading a connector release: SPHERE_RELEASE_SIGNING_KEY is not set, so releases cannot be signed.

Deleting an enrollment token needs a step-up token from the Hub; a missing, expired, reused or foreign step_up_token is a validation error on step_up_token.

Sphere job error codes

Reported by the Sphere connector in job.result.error_code (Sphere connector protocol); a failed stream start shows as a failed stream with the message:

Code	Meaning
nvr_unreachable	The NVR did not answer, is disconnected, or the stream did not start in time.
nvr_auth_failed	The NVR refused the credentials, or the connector has none yet.
channel_invalid	The NVR has no such channel.
stream_limit	The connector publishes as many streams as it may.
codec_unsupported	The stream has no video the relay can pass through (MJPEG).
media_publish_failed	The media server refused or dropped the stream (check outbound TCP 8322 to media.entrosity.com).
no_recordings	Reserved.
unsupported	The driver or the NVR cannot do this (PTZ on a fixed camera).
unknown_driver	The connector has no driver of that name (simulator without --dev).
unknown_nvr	The connector does not drive that NVR.
invalid_payload	The job payload is invalid.
exec_failed	The connector restarted before the job finished, or another failure; for update_agent, the update could not be scheduled.
update_unsigned	Self-update: the connector build has no release public key and refuses updates.
signature_invalid	Self-update: a release signature did not verify.
download_failed, hash_mismatch	Self-update: the MSI could not be downloaded, or does not match the release.

Entrosity Matrix codes

Matrix problem codes

Answers of Matrix's API (Matrix API) and connector API. Sign-in problems come from the Hub (above). Refused changes are also recorded in the history with the code as the detail.

Code	HTTP	Meaning
validation	422	The body or parameters failed validation; fields names each problem (for example a policy_pattern without exactly one (?P<room>…) group, a hostname_suffix without a leading dot, a reenable_at outside 5 minutes to 7 days or with enable, an invalid IP or group version, a release version that is not a semantic version).
malformed_body, body_too_large	400	Unreadable JSON, or larger than allowed.
unauthenticated	401	No, invalid or expired Hub product token, the Hub session ended, or the user is unknown to Matrix or disabled.
forbidden	403	Your role lacks the permission (a viewer switching a room, a teacher changing an address or the list of allowed sites for all rooms).
group_read_only, member_read_only	403	The address group, or the computer, cannot be edited (shared, nested, not a /32, not a direct member); for allowed sites, Matrix may not change the list's group (used as a source or inside another group, nested groups). The detail says why.
invalid_domain	422	Allowed sites: a domain is not valid (an IP address, a path, a character that is not allowed; fields.domains names it), or the list has more than 200 domains.
no_access_rule	403	The route has no access rule (a server bug).
not_found	404	Not found, including resources of another tenant. The detail names the resource (firewall not found).
no_credentials	404	Connector API: no token is stored for the firewall.
(no code)	429	Too many API requests from your IP address.
rate_limited	429	Too many changes (10 per user, 30 per tenant per minute; each room of a bulk change counts), or too many connector enrollments from this IP address.
busy	409	Another change of this room (or an address change of this firewall) is still running.
snapshot_stale	409	The firewall's state is out of date (old report, connector offline, firewall not online): wait for the next report.
connector_offline	409	The firewall's connector is offline (changes, check and refresh need it online).
writes_disabled	409	Changes (or address changes, or allowed-sites editing) are switched off for this firewall.
connector_outdated	409	Allowed sites: the firewall's connector does not support them yet (it did not announce the sites capability); update the connector.
sites_not_set_up	409	Allowed sites: the list's address group or its ACCEPT policy is missing on the FortiGate.
unknown_room	409, 404	409: the firewall does not report this room. 404: a teacher named a room not granted to them (switch, bulk change, re-enable cancel, allowed-sites list; in a bulk change any of its rooms, nothing is sent): rooms a teacher does not see answer like rooms that do not exist.
conflict	409	The address group or IP (or the allowed-sites list) changed since it was loaded: reload and try again.
duplicate_ip	409	Another managed computer has this IP.
duplicate_name	409	An address object with this name exists.
request_id_reused	409	The request_id belongs to another address operation.
not_retryable	409	The address operation never started writing or is complete: send a new request.
schedule_not_pending	409	The re-enable is already firing or finished.
firewall_disabled	409	The firewall is not in use.
firewall_name_taken	409	Another firewall of the tenant has this name.
connector_has_firewalls	409	A connector that still manages firewalls cannot be removed.
site_name_taken	409	A site with this name exists in the tenant.
job_finished	409	The connector reported on a job that has already finished.
not_teacher	422	Room rights can only be given to teachers of the tenant (not_operator before the role was renamed).
enrollment_token_invalid	401	Unknown enrollment token, not a Matrix connector token, or its tenant is suspended.
enrollment_token_exhausted	409	The token has no uses left.
enrollment_token_expired	410	The token expired or was revoked.
invalid_request	422	The enrollment request is invalid.
connector_unauthorized	401	The connector key is unknown or revoked (connector removed, tenant suspended).
invalid_message	422	A connector message, report or HTTP fallback body failed validation.
unauthorized	401	Uploading a connector release: wrong or missing release token, or MATRIX_RELEASE_TOKEN is not set.
release_exists	409	Uploading a connector release: this version is already published.
releases_disabled	503	Uploading a connector release: MATRIX_RELEASE_SIGNING_KEY is not set.

Matrix job error codes

Reported by the Matrix connector in job.result.error_code (Matrix connector protocol), shown with changes and as a firewall's error_code. The last column is the change result it leads to when nothing was written; a code after a write makes the change unconfirmed.

Code	Meaning	Result
forbidden_policy	The policy is not a manageable room policy (name, direction or VDOM).	denied
policy_changed	The policy changed on the FortiGate while it was checked.	denied
room_mismatch	The policy no longer belongs to this room.	denied
unconfirmed	A write was sent but could not be confirmed.	unconfirmed
conflict	The group or the IP (or the allowed-sites list) changed in the meantime.	denied
duplicate_ip, duplicate_name	Another managed computer has the IP; an object with the name exists.	denied
shared_object	The object or group is also used outside the room.	denied
invalid_input	The name or IP address was rejected.	denied
sites_not_set_up	The allowed-sites address group or its ACCEPT policy is missing on the FortiGate.	denied
unauthorized	Matrix refused the write at write time (reasons).	denied
guard_pending	The connector's local guard has not accepted the firewall yet.	denied
guard_mismatch	The firewall's configuration differs from the accepted one.	denied
writes_disabled	Writes are switched off (in Matrix or in the guard).	denied
busy	Another write on the same object is running.	denied
not_found	The object was not found on the FortiGate.	denied
rate_limited	The connector's local write cap per firewall and minute.	denied
expired	The job reached the connector too late.	error
unreachable	No connection to the FortiGate.	error
tls	The FortiGate's certificate could not be verified.	error
auth_failed	The FortiGate answered 401/403 (token, trusted hosts, profile).	error
version_mismatch	The FortiOS version differs from the pinned one.	error
direction_invalid	The source or destination interface or zone was not found.	error
invalid_response	Malformed or inconsistent FortiGate data.	error
unknown_firewall	The connector does not know the firewall yet.	error
unknown_driver	The connector has no such driver (simulator without --dev).	error
interrupted	The connector restarted before anything was written.	error
update_unsigned, signature_invalid, download_failed, hash_mismatch, exec_failed	Self-update, as for the other connectors.	–

Write-time authorization reasons

The reason of a refused POST /api/connector/v1/jobs/{id}/authorize, shown in the change's steps (Matrix connector protocol):

Reason	Meaning
invalid_request	The request is malformed.
unknown_job	No such job for this connector.
job_not_live	The job is not acked or running.
expired	The job's expiry passed.
step_mismatch, values_mismatch	The step does not fit the job type, or its values differ from the job's.
firewall_disabled	The firewall is not in use (or was deleted).
writes_disabled	The firewall's switch for this kind of write is off.
user_inactive	The author is no longer an active user of the tenant.
session_ended	The author's Hub session was ended.
not_permitted	The author's role no longer allows the change.
room_not_granted	The operator no longer holds the room's right.
schedule_not_firing	A system re-enable whose schedule is no longer firing (cancelled or replaced).
services_removed	A matrix.services.sync job left from before the Entrosity services were removed; it is always refused.
not_recorded	The decision could not be recorded; the write is refused.

Entrosity Vertex codes

The problem codes of Vertex's API (not_configured, writes_disabled, deletes_disabled, out_of_scope, protected, rate_limited, step_up_required, import_not_validated, the settings and import validation codes, …) and the error codes of its operations (guard_pending, guard_denied, logon_failed, access_denied, missing_module, password_policy, unauthorized with author_revoked, …), with what to do about each, are listed in Vertex troubleshooting. The connector's job error codes: Vertex protocol → Error codes.

Enrollment

Code	HTTP	Meaning
enrollment_token_invalid	401	Unknown token, or the wrong kind (agent vs connector).
enrollment_token_exhausted	409	No uses left.
enrollment_token_expired	410	Expired or revoked.
agent_unauthorized, connector_unauthorized	401	The key is revoked (decommissioned, deleted, tenant suspended).

Device action skip reasons

Bulk and single device actions skip devices they cannot act on:

Code	Meaning
no_agent	The device has no agent.
decommissioned	The device is decommissioned.
software_not_found	The program is not in the device's inventory.
needs_silent_args	The uninstaller is not silent by itself; give silent arguments.
no_uninstall_method	No usable uninstall command (e.g. Store apps).
no_site	The device has no site, so no connector can wake it.
no_connector	No online connector with wake-on-LAN in the device's site.
no_mac_address	The device's MAC address is unknown.

Job error codes

Reported by agents in job.result.error_code (deployment targets, device actions, script runs):

Code	Meaning
download_failed	The package could not be downloaded.
hash_mismatch	The downloaded file's SHA-256 is wrong (file discarded).
disk_full	Not enough free space for the download.
exec_failed	The installer or script could not be started (e.g. pwsh.exe missing).
exit_code	The exit code is not a success code.
timeout	The job ran longer than its timeout (process tree killed).
detection_failed	The detection rule disagrees with the result.
winget_missing	winget is not installed and could not be bootstrapped.
winget_not_found	winget found no such package.
install_in_progress	Another installation kept running (msiexec 1618, retried 3×).
no_logged_on_user	Run-as-user job, but nobody is signed in.
run_as_unsupported	The agent is older than 0.5.
no_uninstall_method	The server found no way to uninstall.
cancelled	Cancelled.
agent_restarted	The agent restarted during the job and detection did not show success.
signature_invalid	A self-update's signature did not verify.
update_unsigned	The build has no release public key and refuses updates.
unsupported, invalid_payload	The agent does not know the job type, or the payload is invalid.
remote_declined	Remote desktop: the user declined the consent prompt or did not answer within 60 s.
remote_unavailable	Remote desktop: the screen could not be captured (no console session, the helper did not start, or the stream could not be opened).

Agent push (connector)

dns_failed, unreachable, winrm_disabled, auth_failed, access_denied, copy_failed, msiexec_failed, already_installed (success), download_failed, timeout. Causes and fixes: Troubleshooting.

LDAP (connector)

ldap_connect, ldap_bind, ldap_search, tls. Causes and fixes: Troubleshooting.

WebSocket close codes

Code	Meaning	Agent reaction
4003	Key revoked: device decommissioned, connector deleted, or tenant suspended	Stops; reinstalling with a token re-enrolls it
4009	A newer connection of the same installation took over	Reconnects with back-off
1008	Policy violation (e.g. a message before hello)	Reconnects with back-off

Remote desktop streams have their own close codes (4000, 4001, 4003, 4004, 4008, and 1008 for an invalid viewer ticket): see Protocol.