Bridge Errors

Bridge Errors

Common Bridge Errors and How to Read Them

A plugin call rejects its promise with an Error whose message is text from the native side and whose code, when present, is machine-readable. Four typical failures, run in the DevTools console of the running app:

Four failing plugin calls, in the DevTools consoleJavaScript

const tryCall = async (name, call) => {
  try { await call(); return { name, ok: true }; }
  catch ({ code, message }) { return { name, code, message }; }
};
(await Promise.all([
  tryCall('eject', () => Capacitor.Plugins.DiskSpace.eject()),
  tryCall('scan', () => Capacitor.registerPlugin('BarcodeScanner').scan()),
  tryCall('read', () => Capacitor.Plugins.Filesystem.readFile({ path: 'x', directory: 'DATA' })),
  tryCall('share', () => Capacitor.Plugins.Share.share({})),
])).map((result) => JSON.stringify(result)).join('\n');

Output

{"name":"eject","code":"UNIMPLEMENTED","message":"\"DiskSpace.eject()\" is not implemented on
  android"}
{"name":"scan","code":"UNIMPLEMENTED","message":"\"BarcodeScanner\" plugin is not implemented
  on android"}
{"name":"read","code":"OS-PLUG-FILE-0008","message":"'readFile' failed because file at
  '/data/user/0/com.example.booknest/files/x/' does not exist."}
{"name":"share","message":"Must provide a URL or Message or files"}

Reading a rejected plugin call
Symptom	Usual cause	Fix
"X" plugin is not implemented on android	Package missing, or no cap sync since install	npm 2,036 install, npx cap sync, rebuild
"X.method()" is not implemented on android	Method exists only on the web or iOS	Check the plugin docs; guard by platform
A plugin's own code, such as OS-PLUG-FILE-0008	Bad input or missing file	Read the plugin's error table
App vanishes, FATAL EXCEPTION in logcat	Uncaught native exception (Push Notifications)	Fix the native setup; nothing in JS catches it

The first row is the classic after a git pull that added a plugin: the native module arrives only with cap sync and a rebuild. Branch on code where there is one, and catch every plugin call: an uncaught rejection only logs Uncaught (in promise) while the feature silently does nothing.

MENU