{"record":{"id":"545b386885018b08","repo":"bumptech/glide","slug":"requested-frame-must-be-non-negative-or-default-f","errorCode":null,"errorMessage":"Requested frame must be non-negative, or DEFAULT_FRAME, given: {frameTimeMicros}","messagePattern":"Requested frame must be non-negative, or DEFAULT_FRAME, given: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"library/src/main/java/com/bumptech/glide/load/resource/bitmap/VideoDecoder.java","lineNumber":177,"sourceCode":"    this.initializer = initializer;\n    this.factory = factory;\n  }\n\n  @Override\n  public boolean handles(@NonNull T data, @NonNull Options options) {\n    // Calling setDataSource is expensive so avoid doing so unless we're actually called.\n    // For non-videos this isn't any cheaper, but for videos it saves the redundant call and\n    // 50-100ms.\n    return true;\n  }\n\n  @Override\n  public Resource<Bitmap> decode(\n      @NonNull T resource, int outWidth, int outHeight, @NonNull Options options)\n      throws IOException {\n    long frameTimeMicros = options.get(TARGET_FRAME);\n    if (frameTimeMicros < 0 && frameTimeMicros != DEFAULT_FRAME) {\n      throw new IllegalArgumentException(\n          \"Requested frame must be non-negative, or DEFAULT_FRAME, given: \" + frameTimeMicros);\n    }\n    Integer frameOption = options.get(FRAME_OPTION);\n    if (frameOption == null) {\n      frameOption = DEFAULT_FRAME_OPTION;\n    }\n    DownsampleStrategy downsampleStrategy = options.get(DownsampleStrategy.OPTION);\n    if (downsampleStrategy == null) {\n      downsampleStrategy = DownsampleStrategy.DEFAULT;\n    }\n\n    final Bitmap result;\n    MediaMetadataRetriever mediaMetadataRetriever = factory.build();\n    try {\n      initializer.initializeRetriever(mediaMetadataRetriever, resource);\n      result =\n          decodeFrame(\n              resource,","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/bumptech/glide/blob/eb14a895d8f866e6a08c3e19d50ea3bd2c12c20a/library/src/main/java/com/bumptech/glide/load/resource/bitmap/VideoDecoder.java#L159-L195","documentation":"IllegalArgumentException thrown by VideoDecoder.decode() when the TARGET_FRAME option is set to a value that is negative and not equal to DEFAULT_FRAME (Long.MIN_VALUE). Frame times must be non-negative microseconds or the DEFAULT_FRAME sentinel.","triggerScenarios":"Setting option VideoDecoder.TARGET_FRAME to a negative long via .set(VideoDecoder.TARGET_FRAME, -1L). Also from passing a calculated negative frame offset (e.g. video duration - X where X exceeds duration).","commonSituations":"Trying to grab a thumbnail at a time computed from metadata where the computation underflows to a negative value. Using -1 as a 'default' sentinel instead of VideoDecoder.DEFAULT_FRAME.","solutions":["Use VideoDecoder.DEFAULT_FRAME instead of -1 when you want the default frame.","Clamp computed frame times to >= 0 before setting the option.","Validate the requested frame time against the video's duration (from MediaMetadataRetriever) before decoding."],"exampleFix":"// before\nGlide.with(ctx).asBitmap().load(videoUri)\n  .set(VideoDecoder.TARGET_FRAME, durationMs - leadInMs) // can be negative\n  .into(img);\n// after\nlong frame = Math.max(0, durationMs - leadInMs);\nGlide.with(ctx).asBitmap().load(videoUri)\n  .set(VideoDecoder.TARGET_FRAME, frame == 0 ? VideoDecoder.DEFAULT_FRAME : frame)\n  .into(img);","handlingStrategy":"validation","validationCode":"// Clamp frame time before setting TARGET_FRAME.\nlong frame = requestedFrameMicros;\nif (frame < 0) frame = VideoDecoder.DEFAULT_FRAME;\nGlide.with(ctx).asBitmap().load(videoUri)\n  .set(VideoDecoder.TARGET_FRAME, frame)\n  .into(img);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use VideoDecoder.DEFAULT_FRAME as the 'no preference' sentinel.","Clamp computed frame times to >= 0.","Validate against video duration before decoding."],"tags":["video","decoder","validation","android"],"backgroundTag":null,"analyzedSha":"eb14a895d8f866e6a08c3e19d50ea3bd2c12c20a","analyzedAt":"2026-08-14T01:43:54.821Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}