Errors

dotlottie-io's Node.js and Browser bindings throw regular JavaScript Error objects. This page lists the conditions that cause them.

Password protection

Message	Cause
`"password required to open this archive"`	The archive is encrypted, but no `password` argument was provided.
`"wrong password or corrupted archive"`	The provided password is incorrect, or the archive is corrupted.

try {
  DotLottie.fromBytes(protectedBytes);
} catch (e) {
  console.error(e.message); // "password required to open this archive"
}

See How to Password-Protect a .lottie File.

Invalid audio format

addAudio (on DotLottie and DotLottieBuilder) throws InvalidAudioFormat if filename doesn't end in .mp3. This is the only supported audio format.

Unknown ID on removal

removeAnimation, removeTheme, and removeStateMachine all throw if the given id doesn't exist in the package. There's no silent no-op for a missing ID — check animationIds()/themeIds()/stateMachineIds() first if you're not sure the ID is present.

Merge collisions

When using DotLottieMerger or DotLottieBuilder.mergeStrategy() with MergeStrategy.Fail, merge()/build() throws on the first ID or filename collision encountered. See the MergeStrategy table for how this differs from Rename and Skip.

Builder validation

DotLottieBuilder.build() throws if any queued content is invalid — for example, a non-.mp3 audio file queued via addAudio.