What causes "from must be a non-negative integer" in remotion-dev/remotion?

Ensure the caller clamps the index: use Math.max(0, Math.round(index)) and pass null when no position is intended

from must be a non-negative integer

Error message

from must be a non-negative integer

What it means

insertElementHandler inserts an element into a composition at an optional index `from`. The handler validates that `from`, when not null, is a finite non-negative integer. Anything else (negative numbers, floats, NaN, Infinity, non-numbers that slipped past typing) is rejected with this error before the install plan is computed.

Source

Thrown at packages/studio-server/src/preview-server/routes/insert-element.ts:73

		element,
		installationName,
		expectedFileState,
		from,
		position,
		overwriteExisting,
	},
	entryPoint,
	remotionRoot,
	logLevel,
}) =>
	withSourceFileWriteQueue(async () => {
		try {
			validateElementInstallPosition(position);
			if (
				from !== null &&
				(!Number.isInteger(from) || !Number.isFinite(from) || from < 0)
			) {
				throw new Error('from must be a non-negative integer');
			}

			const installationMode =
				element.installationMode === null
					? 'wrapped'
					: element.installationMode;
			const componentOwnsSequence =
				installationMode === 'component-owned-sequence';

			RenderInternals.Log.trace(
				{indent: false, logLevel},
				`[insert-element] Received request for compositionFile="${compositionFile}" compositionId="${compositionId}" element="${element.slug}"`,
			);

			const plan = await getElementInstallPlan({
				installationName,
				destination: {
					type: 'current-composition',

View on GitHub (pinned to b2f4e34732)

Solutions

Ensure the caller clamps the index: use Math.max(0, Math.round(index)) and pass null when no position is intended
Fix the client that passes -1 (e.g. from indexOf of a missing element) — convert -1 to null or 0
If calling the HTTP API directly, send a valid integer >= 0 or JSON null

Example fix

// before
await insertElement({from: children.indexOf(el)}); // -1 when missing
// after
const idx = children.indexOf(el);
await insertElement({from: idx === -1 ? null : idx});

Defensive patterns

Strategy: validation

Validate before calling

const validFrom = (from: number | null): number | null =>
  from === null || (Number.isInteger(from) && Number.isFinite(from) && from >= 0) ? from : null;

Type guard

const isValidFrom = (from: unknown): from is number => typeof from === 'number' && Number.isInteger(from) && Number.isFinite(from) && from >= 0;

Try / catch

try {
  await studio.insertElement({..., from});
} catch (e) {
  if (String(e).includes('from must be a non-negative integer')) {
    await studio.insertElement({..., from: null}); // retry without position
  } else throw e;
}

Prevention

Convert -1 results from indexOf() to null before sending an insert request
Clamp and round computed indices: Math.max(0, Math.round(idx))
Validate request bodies client-side before calling the studio insert-element API

When it happens

Trigger: Sending an InsertElementRequest to the studio preview server with from = -1, a fractional value like 1.5, NaN/Infinity, or a malformed value from a client that bypasses typing.

Common situations: Client code computing the insert index as indexOf() returning -1 and passing it through unguarded; stale client state sending placeholder values; hand-rolled API calls to the studio server.

Related errors

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-02). Data as JSON: /api/errors/fb6fe6cc0495108e. Report an issue: GitHub.