{"record":{"id":"2a0dcdbeb954aed1","repo":"remotion-dev/remotion","slug":"samples-must-be-max-samples-but-got-sam","errorCode":null,"errorMessage":"\"samples\" must be <= ${MAX_SAMPLES}, but got ${samples}","messagePattern":"\"samples\" must be <= (.+?), but got (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/effects/src/light-trail/index.ts","lineNumber":137,"sourceCode":"\tdistance: p.distance ?? DEFAULT_DISTANCE,\n\tintensity: p.intensity ?? DEFAULT_INTENSITY,\n\tdecay: p.decay ?? DEFAULT_DECAY,\n\tthreshold: p.threshold ?? DEFAULT_THRESHOLD,\n\tsamples: p.samples ?? DEFAULT_SAMPLES,\n\tcolor: p.color ?? DEFAULT_COLOR,\n});\n\nconst validateSamples = (samples: number): void => {\n\tif (!Number.isInteger(samples)) {\n\t\tthrow new TypeError(`\"samples\" must be an integer, but got ${samples}`);\n\t}\n\n\tif (samples < 1) {\n\t\tthrow new TypeError(`\"samples\" must be >= 1, but got ${samples}`);\n\t}\n\n\tif (samples > MAX_SAMPLES) {\n\t\tthrow new TypeError(\n\t\t\t`\"samples\" must be <= ${MAX_SAMPLES}, but got ${samples}`,\n\t\t);\n\t}\n};\n\nconst validateLightTrailParams = (params: LightTrailParams): void => {\n\tassertEffectParamsObject(params, 'Light trail');\n\tassertOptionalFiniteNumber(params.direction, 'direction');\n\tassertOptionalFiniteNumber(params.distance, 'distance');\n\tassertOptionalFiniteNumber(params.intensity, 'intensity');\n\tassertOptionalFiniteNumber(params.decay, 'decay');\n\tassertOptionalFiniteNumber(params.threshold, 'threshold');\n\tassertOptionalFiniteNumber(params.samples, 'samples');\n\tassertOptionalColor(params.color, 'color');\n\n\tconst r = resolve(params);\n\tvalidateNonNegative(r.distance, 'distance');\n\tvalidateNonNegative(r.intensity, 'intensity');","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/effects/src/light-trail/index.ts#L119-L155","documentation":"Thrown by @remotion/effects' lightTrail effect when `samples` exceeds MAX_SAMPLES (64). The upper bound caps GPU cost: each extra sample adds a directional texture fetch in the fragment shader, so 64 is the safety ceiling before frame budgets blow out during rendering.","triggerScenarios":"Calling `lightTrail({samples: 65})` or any integer > 64. Values 1..64 are accepted; integers below 1 throw error 680; non-integers throw the integer-guard error first.","commonSituations":"Slider/expression returning large numbers (e.g. an unbounded `interpolate`); porting a config from a different effect with a higher cap; assuming 'more samples = better' and cranking it past 64; multiplying samples by devicePixelRatio.","solutions":["Clamp to the documented range: `samples: Math.min(64, Math.max(1, Math.round(v)))`.","If you need a longer streak, raise `distance` or `intensity` instead of `samples` — both raise cost more gracefully.","Omit the prop entirely to use the default of 32, which is tuned for quality/perf.","Check any Studio Visual Mode slider binding isn't exceeding the schema's `max`."],"exampleFix":"// before\nlightTrail({ samples: Math.round(pixelsOfStreak / 2) });\n\n// after\nlightTrail({ samples: Math.min(64, Math.max(1, Math.round(pixelsOfStreak / 2))) });","handlingStrategy":"validation","validationCode":"const MAX_SAMPLES = 64;\nconst safeSamples = (v: unknown): number | undefined => {\n  if (v === undefined) return undefined;\n  if (typeof v !== 'number' || !Number.isFinite(v)) {\n    throw new TypeError('samples must be a finite number');\n  }\n  return Math.min(MAX_SAMPLES, Math.max(1, Math.round(v)));\n};\nconst samples = safeSamples(userSamples);\nlightTrail(samples === undefined ? {} : { samples });","typeGuard":"const isSamples = (v: unknown): v is number =>\n  typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 64;","tryCatchPattern":null,"preventionTips":["Clamp any externally sourced samples value into [1, 64].","When you need a more pronounced trail, raise distance/intensity instead of samples.","Bind UI sliders to the documented max of 64."],"tags":["validation","light-trail","effects","performance-budget"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}