juicedata/juicefs · info

ErrSkipped

ErrSkipped

Error message

skipped

What it means

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.

Source

Thrown at pkg/utils/errors.go:27

 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package utils

import (
	"errors"
	"syscall"
)

var (
	ErrNotSUP      = errors.New("not supported")
	ErrFuncTimeout = errors.New("function timeout")
	ErrSkipped     = errors.New("skipped")
	ErrExtlink     = syscall.Errno(1000)
)

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Exclude special files (.stats, .config, .accesslog, etc.) from your source listing
  2. Check for utils.ErrSkipped with errors.Is and treat it as success/skip rather than failure
  3. Filter keys through vfs.IsSpecialName before writing

Example fix

// before
err := dst.Put(ctx, key, r)
if err != nil { return err }
// after
err := dst.Put(ctx, key, r)
if errors.Is(err, utils.ErrSkipped) { return nil } // special file, ignore
Defensive patterns

Strategy: try-catch

Validate before calling

if vfs.IsSpecialName(key) {
	return nil // skip before calling Put/UploadMultipart
}

Type guard

func isSkipped(err error) bool { return errors.Is(err, utils.ErrSkipped) }

Try / catch

err := dst.Put(ctx, key, r)
if err != nil {
	if errors.Is(err, utils.ErrSkipped) {
		return nil // special file intentionally skipped
	}
	return err
}

Prevention

When it happens

Trigger: 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".

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/ecb51f0483cd87e1. Report an issue: GitHub.