Troubleshooting

Native module is missing after installation

Confirm both the library and compatible Nitro Modules are installed; install iOS pods where applicable and rebuild the native application. A Metro reload alone does not add native code.

Web or Expo Go throws

Native processing requires an Android/iOS native build containing the package. A web preview is an interface preview only.

iOS picker returned ph://

Export or copy the Photos asset to a readable local file using the app's picker/Photos integration, then supply that path.

Android content:// input cannot be read

Check provider permissions and keep the read grant valid for the entire operation, or copy the asset into app-readable local storage.

Output already exists

Omit outputFileName for a unique default name, choose another filename, or deliberately enable overwrite.

Output filename rejected

Supply only a filename with .mp4 or .jpg as appropriate, with no directory separators/control characters.

One compression cancels another

The calls shared a session. Use independent compressors/hooks, or use a sequential batch.

Cancel button stops the wrong export

Match cancelCompress() to top-level compression, session.cancel() to that session, hook cancel() to that hook, and AbortController.abort() to a batch.

Hook error remains null after a rejected call

JavaScript validation happens before hook state changes. Catch the returned compressVideo promise as well.

Result dimensions differ from the requested size

Limits form a bounding box, aspect ratio is retained without upscaling, and encoded video dimensions round down to even pixels. Inspect output metadata.

File is larger than the source

Re-encoding can enlarge an efficient input. Try suitable bitrate/dimension limits and compare before replacing originals. No preset guarantees a percentage reduction.

HEVC or an audio setting fails

Encoder capabilities vary. Choose supported settings or explicitly retry H.264 as an app-level decision.

Cached file disappeared

Move/copy outputs into permanent storage before relying on them long term. Cache lifetime is controlled by the OS.

Need precise frame edits or subtitle/metadata preservation

Those are not guaranteed features of this API. Thumbnails/trim boundaries depend on media timestamps and platform decoders/encoders.

Need guaranteed HDR output

HDR preservation and consistent tone mapping are not promised. Test target devices and inputs rather than advertising universal support.