mrdoob/three.js · error

THREE.KeyframeTrack: track name is undefined

Error message

THREE.KeyframeTrack: track name is undefined

What it means

Thrown by the KeyframeTrack constructor when the name argument is undefined. The track name encodes the property binding (e.g. 'bone.position', 'mesh.morphTargetInfluences[0]') and is mandatory; without it the track cannot be bound to any object. The check runs before times/values validation.

Source

Thrown at src/animation/KeyframeTrack.js:31

/**
 * Represents a timed sequence of keyframes, which are composed of lists of
 * times and related values, and which are used to animate a specific property
 * of an object.
 */
class KeyframeTrack {

	/**
	 * Constructs a new keyframe track.
	 *
	 * @param {string} name - The keyframe track's name.
	 * @param {Array<number>} times - A list of keyframe times.
	 * @param {Array<number|string|boolean>} values - A list of keyframe values.
	 * @param {(InterpolateLinear|InterpolateDiscrete|InterpolateSmooth|InterpolateBezier)} [interpolation] - The interpolation type.
	 */
	constructor( name, times, values, interpolation ) {

		if ( name === undefined ) throw new Error( 'THREE.KeyframeTrack: track name is undefined' );
		if ( times === undefined || times.length === 0 ) throw new Error( 'THREE.KeyframeTrack: no keyframes in track named ' + name );

		/**
		 * The track's name can refer to morph targets or bones or
		 * possibly other values within an animated object. See {@link PropertyBinding#parseTrackName}
		 * for the forms of strings that can be parsed for property binding.
		 *
		 * @type {string}
		 */
		this.name = name;

		/**
		 * The keyframe times.
		 *
		 * @type {Float32Array}
		 */
		this.times = AnimationUtils.convertArray( times, this.TimeBufferType );

View on GitHub (pinned to da05705fa3)

Solutions

  1. Pass a non-empty name string as the first argument, following the PropertyBinding track-name grammar (nodeName.property or the documented forms).
  2. If the name comes from data, default/validate it before constructing the track and skip or log when it is absent.
  3. Double-check destructuring/argument order: new KeyframeTrack(name, times, values, interpolation).

Example fix

// before
tracks.push( new KeyframeTrack( cfg.prop, times, values ) ); // cfg.prop is undefined

// after
if ( ! cfg.prop ) throw new Error( 'track config missing prop name' );
tracks.push( new KeyframeTrack( cfg.prop, times, values ) );
Defensive patterns

Strategy: type-guard

Validate before calling

function makeTrack( name, times, values, interpolation ) {
  if ( typeof name !== 'string' || name.length === 0 ) {
    throw new TypeError( 'KeyframeTrack requires a non-empty name' );
  }
  return new THREE.KeyframeTrack( name, times, values, interpolation );
}

Type guard

function isValidTrackName( name ) {
  return typeof name === 'string' && name.length > 0 && name.includes( '.' );
}

Try / catch

try {
  track = new THREE.KeyframeTrack( name, times, values );
} catch ( err ) {
  if ( /track name is undefined/.test( err.message ) ) {
    throw new Error( `Refusing to build track: name resolved to undefined (source=${String(name)})` );
  }
  throw err;
}

Prevention

When it happens

Trigger: Constructing new KeyframeTrack(undefined, times, values). Building tracks programmatically and forgetting to pass the name, or passing a variable that resolved to undefined (e.g. a missing field on a config object).

Common situations: Programmatic animation builders where the property path is computed from data that can be absent. Deserialization code that reads track.name from JSON without defaulting. Destructuring bugs that drop the name.

Related errors

AI-assisted analysis of mrdoob/three.js@da05705fa3 (2026-08-12). Data as JSON: /api/errors/3efa568a08692a2c. Report an issue: GitHub.