Skip to content

Commit 3974950

Browse files
stevenmatthewstevenmatthew
committed
New article for agent status codes
1 parent 5c13d4b commit 3974950

File tree

1 file changed

+218
-0
lines changed

1 file changed

+218
-0
lines changed

‎articles/storage-mover/xdm-status.md

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
title: Agent job error codes
3+
description: Learn how to understand and remediate errors raised by the Azure Storage Mover Agent.
4+
author: stevenmatthew
5+
ms.author: shaas
6+
ms.service: storage-mover
7+
ms.topic: how-to
8+
ms.date: 03/10/2023
9+
ms.custom: template-how-to
10+
---
11+
12+
<!--
13+
!########################################################
14+
STATUS: IN REVIEW
15+
16+
CONTENT: final
17+
18+
REVIEW Stephen/Fabian: not reviewed
19+
REVIEW Engineering: not reviewed
20+
EDIT PASS: not started
21+
22+
!########################################################
23+
-->
24+
25+
# Agent Job Error Codes
26+
27+
An Azure Storage Mover agent uses string status codes for statuses that are conveyed to the end user. All XDM status codes have the prefix *AZSM* followed by 4 decimal digits. The first decimal digit indicates the high-level scope of the status. Each status code should belong to one of the following scopes:
28+
29+
1. Status that applies to the entire agent.<br />These use the scope digit '0' and hence have the prefix "AZSM0".
30+
1. Status that applies to a specific job that is being run by the agent.<br />These use the scope digit '1' and hence have the prefix "AZSM1".
31+
1. Status that applies to a specific file/dir being transferred by a job that is being run by the agent.<br />These use the scope digit '2' and hence have the prefix "AZSM2".
32+
33+
Each of these scopes can then further divide the statuses into categories and sub-categories and typically reserve 20 status codes for each sub-category to accommodate future expansion.
34+
35+
> [!IMPORTANT]
36+
> *AZSM0000* is the special scope-agnostic status code indicating successful operation. This should be used to signify successful operation at any scope/level.
37+
38+
|Error Code |Error Message | Details/Troubleshooting steps/Mitigation |
39+
|---------------------------------|--------------|------------------------------------------|
40+
| <a href="AZSM1001">AZSM1001</a> |Failed to mount source path | Verify the provided server information, name or IP-address, is valid, or the source location is correct.
41+
| <a href="AZSM1002">AZSM1002</a> |Encountered an error while scanning the source | Retry or create a support ticket. |
42+
| <a href="AZSM1003">AZSM1003</a> |Failed to access source folder due to permission issues | Check if the agent has been granted permissions correctly to the source file share. |
43+
| <a href="AZSM1004">AZSM1004</a> |Source path provided is invalid | Create a new endpoint with a valid source share path and update the job definition and retry. |
44+
| <a href="AZSM1020">AZSM1020</a> |Miscellaneous error while accessing source | Retry or create a support ticket. |
45+
| <a href="AZSM1021">AZSM1021</a> |Failed to access target folder due to permission issues | Retry or create a support ticket. |
46+
| <a href="AZSM1022">AZSM1022</a> |Target path provided is invalid | Create a new endpoint with a valid target container and path and update the job definition and retry. |
47+
| <a href="AZSM1023">AZSM1023</a> |Lease expired for this agent on the target container | Retry or create a support ticket. |
48+
| <a href="AZSM1024">AZSM1024</a> |Authorization failure on claiming the target container | The agent does not have the permission to access the target container. The role assignment is performed automatically while running jobs from the portal. If you are using the APIs/Powershell cmdlets/SDKs, then manually create a 'Storage Blob Data Contributor' role assignment for the agent to access the target storage account blob container. The [Assign an Azure role for access to blob data](/azure/storage/blobs/assign-azure-role-data-access) article may help resolve this issue. |
49+
| <a href="AZSM1025">AZSM1025</a> |Authentication failure on claiming the target container | Retry or create a support ticket. |
50+
| <a href="AZSM1026">AZSM1026</a> |Blob type in the target container not supported by the agent | This blob type is unsupported by the current Storage Mover agent. |
51+
| <a href="AZSM1040">AZSM1040</a> |Miscellaneous error while accessing target | Retry or create a support ticket. |
52+
| <a href="AZSM1041">AZSM1041</a> |Failed to send job progress | Retry or create a support ticket. |
53+
| <a href="AZSM1042">AZSM1042</a> |Failed to create job | Retry or create a support ticket. |
54+
| <a href="AZSM1043">AZSM1043</a> |Failed to resume job | Retry or create a support ticket. |
55+
| <a href="AZSM1044">AZSM1044</a> |Failed to finalize the job | Retry or create a support ticket. |
56+
| <a href="AZSM1045">AZSM1045</a> |Job was aborted while it was still running | Retry or create a support ticket. |
57+
| <a href="AZSM1060">AZSM1060</a> |Miscellaneous error during job execution | Retry or create a support ticket. |
58+
59+
## I'd like to retain any content below this section for future work
60+
61+
I'd like to retain any content below this section for future work.
62+
63+
## Upgrade Related Errors (status code range == 01-20)
64+
65+
|Status code| Description |
66+
|-----------|-----------------------------------------------|
67+
|"AZSM0001" | Image download during agent upgrade failed. |
68+
|"AZSM0002" | Pre-upgrade checks for agent upgrade failed. |
69+
|"AZSM0003" | Actual upgrade process failed. |
70+
|"AZSM0004" | Post-upgrade checks for agent upgrade failed. |
71+
|"AZSM0005" | Rollback for agent upgrade failed. |
72+
73+
74+
## Job run-specific status codes
75+
76+
Status codes for various job run failures. These should cover *all* possible cases of job runs failures. These will be conveyed to the user as part of "jobrunlog" telling what happened to the job.
77+
78+
Based on the reason for job run failure these are grouped under the following categories:
79+
80+
### Source Related Errors (status code range == 01-20)
81+
82+
|Status code| Description |
83+
|-----------|------------------------------------------------------------|
84+
|"AZSM1001" | Cannot mount source path. |
85+
|"AZSM1002" | Scanning failed for the job. |
86+
|"AZSM1003" | Cannot access source folder/file due to permission issues. |
87+
|"AZSM1004" | Invalid source path provided. |
88+
|"AZSM1020" | Cannot access target folder due to other issues. |
89+
90+
### Target Related Errors (status code range == 21-40)
91+
92+
|Status code| Description |
93+
|-----------|---------------------------------------------------------------|
94+
|"AZSM1021" | Cannot access target folder due to permission issues. |
95+
|"AZSM1022" | Invalid target path provided. |
96+
|"AZSM1023" | Lease expired for the target container for agent. |
97+
|"AZSM1024" | Authorization failure on claiming the target container. |
98+
|"AZSM1025" | Authentication failure on claiming the target container. |
99+
|"AZSM1026" | Blob type in the target container not supported by the agent. |
100+
|"AZSM1027" | Target container is being used by some other job. |
101+
|"AZSM1040" | Cannot access target folder due to other issues. |
102+
103+
### Other errors, not related to source or target access (status code range == 41-60)
104+
105+
|Status code| Description |
106+
|-----------|------------------------------|
107+
|"AZSM1041" | Unable to send job progress. |
108+
|"AZSM1042" | Failed to create job. |
109+
|"AZSM1043" | Failed to resume the job. |
110+
|"AZSM1044" | Failed to finalize the job. |
111+
|"AZSM1045" | Job canceled. |
112+
|"AZSM1060" | Job failed. |
113+
114+
## Copy failure-specific status codes
115+
116+
Status codes for various copy failures. These should cover *all* possible reasons which prevent a source file from being copied to target. These will be conveyed to the user as part of "copylog" telling "why" the given file was not copied. Based on the reason for copy failure these are grouped under the following categories:
117+
118+
### Excluded (status code range 01 - 20)
119+
120+
The file was excluded by at least one user specified filter. This is not actually an error but neverthless we make a note of it to let user know that these files were skipped due to some exclusion filter.
121+
122+
|Status code| Description |
123+
|-----------|----------------------------------------------------------|
124+
|"AZSM2001" | File was excluded by at least one user specified filter. |
125+
126+
### Unsupported (status code range 21 - 40)
127+
128+
One or more of the source file's characteristics makes it unfit for storing in the target, e.g., the source file may have deeper directory depths than what the target supports, or it may have path/component lengths longer than that supported by the target, or it may be a filetype not supported by the target, etc.
129+
130+
|Status code| Description |
131+
|-----------|----------------------------------------------------------|
132+
|"AZSM2021" | Filetype in source cannot be stored in the target. |
133+
|"AZSM2022" | Source file path has one or more characters that are not supported by the target. |
134+
|"AZSM2023" | Source file path has one or more components that have length larger than max component length supported by target namespace. |
135+
|"AZSM2024" | Source file path has total length larger than max path length supported by target namespace. |
136+
|"AZSM2025" | Source file path has directory depth larger than what target namespace supports. |
137+
|"AZSM2026" | Source file size is larger than what target supports. |
138+
139+
### NoCopyNecessary (status code range AZSM2041 - AZSM2060)
140+
141+
The sync engine concluded that the file does not need to be copied as it has not changed since last sync. File was inferred by sync engine as "unchanged since last sync hence not needing copy".
142+
143+
|Status code| Description |
144+
|-----------|------------------------------|
145+
|"AZSM2041" | By file time |
146+
|"AZSM2042" | By target compare |
147+
148+
### Failed (status code range == AZSM2061 - AZSM2080)
149+
150+
The copy failed due to some transient reason, either while reading from the source or writing to the target.
151+
152+
|Status code| Description |
153+
|-----------|------------------------------|
154+
155+
|"AZSM2061" | Error encountered when scanning the source. |
156+
|"AZSM2062" | Could not read source file due to permission issues. |
157+
|"AZSM2063" | Encountered I/O error while reading source file. |
158+
|"AZSM2064" | Timed out while reading source file. |
159+
|"AZSM2065" | Transport error when sending file to target. |
160+
|"AZSM2066" | Status returned by target. |
161+
|"AZSM2067" | Timed out while writing file to target. |
162+
|"AZSM2068" | Error encountered when scanning the target. |
163+
|"AZSM2069" | Could not read/write target file due to permission issues. |
164+
|"AZSM2070" | Could not write target file because a lease is active. |
165+
166+
<!--
167+
AgentStatusMap holds a small description string corresponding to agent statuses.
168+
--------------------------------------------------------------------------------
169+
XDM_AGSTATUS_UPG_DOWNLOAD_FAILED: "Image download failed for agent upgrade",
170+
XDM_AGSTATUS_UPG_PRE_CHECK_FAILED: "Pre-upgrade checks failed for agent upgrade",
171+
XDM_AGSTATUS_UPG_UPGRADE_FAILED: "Actual upgrade failed for agent upgrade",
172+
XDM_AGSTATUS_UPG_POST_CHECK_FAILED: "Post upgrade checks failed for agent upgrade",
173+
XDM_AGSTATUS_UPG_ROLLBACK_FAILED: "Rollback failed for agent upgrade",
174+
175+
JobRunLogStatusMap holds a small description string corresponding to jobrun log statuses.
176+
-----------------------------------------------------------------------------------------
177+
XDM_JLSTATUS_SRC_MNT_FAILED: "Failed to mount source path",
178+
XDM_JLSTATUS_SRC_SCAN_FAILED: "Encountered an error while scanning the source",
179+
XDM_JLSTATUS_SRC_PERM: "Failed to access source folder due to permission issues",
180+
XDM_JLSTATUS_SRC_INVALID_PATH: "Source path provided is invalid",
181+
XDM_JLSTATUS_SRC_UNKNOWN: "Miscellaneous error while accessing source",
182+
XDM_JLSTATUS_TGT_PERM: "Failed to access target folder due to permission issues",
183+
XDM_JLSTATUS_TGT_INVALID_PATH: "Target path provided is invalid",
184+
XDM_JLSTATUS_TGT_LEASE_EXPIRED: "Lease expired for this agent on the target container",
185+
XDM_JLSTATUS_TGT_AUTHZ: "Authorization failure on claiming the target container",
186+
XDM_JLSTATUS_TGT_AUTHN: "Authentication failure on claiming the target container",
187+
XDM_JLSTATUS_TGT_BLOBTYPE: "Blob type in the target container not supported by the agent",
188+
XDM_JLSTATUS_TGT_UNKNOWN: "Miscellaneous error while accessing target",
189+
XDM_JLSTATUS_OTHER_JOB_PROGRESS_FAILURE: "Failed to send job progress",
190+
XDM_JLSTATUS_OTHER_CREATE_JOB_FAILED: "Failed to create job",
191+
XDM_JLSTATUS_OTHER_RESUME_FAILED: "Failed to resume job",
192+
XDM_JLSTATUS_OTHER_FINALIZE_JOB_FAILED: "Failed to finalize the job",
193+
XDM_JLSTATUS_OTHER_JOB_CANCELED: "Job was aborted while it was still running",
194+
XDM_JLSTATUS_OTHER_UNKNOWN: "Miscellaneous error during job execution",
195+
XDM_JLSTATUS_TGT_CONTAINER_BUSY: "Target container is in use by some other job",
196+
197+
CopyLogStatusMap holds a small description string corresponding to copylog statuses.
198+
------------------------------------------------------------------------------------
199+
XDM_CLSTATUS_EXCLUDED: "File excluded by a user specified filter",
200+
XDM_CLSTATUS_UNSUPP_FILETYPE: "File type not supported by target",
201+
XDM_CLSTATUS_UNSUPP_CHAR: "One or more characters in source filename not supported by target",
202+
XDM_CLSTATUS_UNSUPP_COMPONENT_LENGTH: "One or more source path components longer than max supported by target",
203+
XDM_CLSTATUS_UNSUPP_TOTAL_LENGTH: "Source path length longer than max supported by target",
204+
XDM_CLSTATUS_UNSUPP_DIR_DEPTH: "Source path has directory depth larger than max supported by target",
205+
XDM_CLSTATUS_UNSUPP_FILE_SIZE: "Source file has size larger than max supported by target",
206+
XDM_CLSTATUS_NCN_BY_FILETIME: "File has not changed since last sync as per filetime check",
207+
XDM_CLSTATUS_NCN_BY_TARGETCOMPARE: "File has not changed since last sync as per target compare check",
208+
XDM_CLSTATUS_FAILED_TARGET_SCANFAILED: "Encountered an error while scanning the target",
209+
XDM_CLSTATUS_FAILED_TARGET_PERM: "Failed to read target file due to permission issues",
210+
XDM_CLSTATUS_FAILED_SOURCE_PERM: "Failed to read source file due to permission issues",
211+
XDM_CLSTATUS_FAILED_SOURCE_IO: "Encountered I/O error while reading source file",
212+
XDM_CLSTATUS_FAILED_SOURCE_TIMEDOUT: "Timed out while reading source file",
213+
XDM_CLSTATUS_FAILED_SOURCE_SCANFAILED: "Encountered an error while scanning the source",
214+
XDM_CLSTATUS_FAILED_TARGET_TRANSPORT: "Transport error when sending file to target",
215+
XDM_CLSTATUS_FAILED_TARGET_IO: "Target failed file copy with an error",
216+
XDM_CLSTATUS_FAILED_TARGET_TIMEDOUT: "Timed out while writing file to target",
217+
XDM_CLSTATUS_FAILED_TARGET_PERM_LEASED: "Cannot write blob because it has an active lease",
218+
-->

0 commit comments

Comments
 (0)