{"record":{"id":"ecb51f0483cd87e1","repo":"juicedata/juicefs","slug":"errskipped","errorCode":"ErrSkipped","errorMessage":"skipped","messagePattern":"skipped","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"info","filePath":"pkg/utils/errors.go","lineNumber":27,"sourceCode":" *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\npackage utils\n\nimport (\n\t\"errors\"\n\t\"syscall\"\n)\n\nvar (\n\tErrNotSUP      = errors.New(\"not supported\")\n\tErrFuncTimeout = errors.New(\"function timeout\")\n\tErrSkipped     = errors.New(\"skipped\")\n\tErrExtlink     = syscall.Errno(1000)\n)\n","sourceCodeStart":9,"sourceCodeEnd":30,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/utils/errors.go#L9-L30","documentation":"utils.ErrSkipped is a sentinel meaning the operation was intentionally skipped. In cmd/object.go, the JuiceFS object-storage wrapper returns it (wrapped) when the target key is a special file name (e.g. control files), and shouldRetry uses it to avoid retrying skipped operations.","triggerScenarios":"Put or CreateMultipartUpload on the JuiceFS storage adapter with a key matching vfs.IsSpecialName (like .stats, .config); the error propagates wrapped as \"skip special file %s for jfs\".","commonSituations":"Syncing or writing a whole mounted directory where kernel/vfs special files (control pseudo-files) appear in the listing; sync tools enumerating the FUSE mount root.","solutions":["Exclude special files (.stats, .config, .accesslog, etc.) from your source listing","Check for utils.ErrSkipped with errors.Is and treat it as success/skip rather than failure","Filter keys through vfs.IsSpecialName before writing"],"exampleFix":"// before\nerr := dst.Put(ctx, key, r)\nif err != nil { return err }\n// after\nerr := dst.Put(ctx, key, r)\nif errors.Is(err, utils.ErrSkipped) { return nil } // special file, ignore","handlingStrategy":"try-catch","validationCode":"if vfs.IsSpecialName(key) {\n\treturn nil // skip before calling Put/UploadMultipart\n}","typeGuard":"func isSkipped(err error) bool { return errors.Is(err, utils.ErrSkipped) }","tryCatchPattern":"err := dst.Put(ctx, key, r)\nif err != nil {\n\tif errors.Is(err, utils.ErrSkipped) {\n\t\treturn nil // special file intentionally skipped\n\t}\n\treturn err\n}","preventionTips":["Filter special names (.stats, .config, .accesslog) out of listings before sync","Compare with errors.Is, not string equality, since it is usually wrapped","Design copy pipelines to treat skips as success"],"tags":["sync","special-files","skip"],"backgroundTag":"unsupported-operation","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}