Troubleshooting

Quick Diagnostic Flow

Set logLevel: 'debug' in the Metro configuration.
Restart Metro with cache clear.
Check skip reasons in logs.
Compare the message with the relevant optimizer page.

Common Issues

No optimization logs at all

Likely causes:

withBoostConfig is missing from metro.config.js
logLevel: 'silent'
File matched by ignores

Quick check:

module.exports = withBoostConfig(config, {
  logLevel: 'debug',
});

npm start -- --clear

Skip reason: `contains blacklisted props`

This is expected for a Text with press or responder props. The native text host does not provide the wrapper behavior these props need. View can translate its accessibility props, tabIndex, and id; see the Native View optimizer.

Fix options:

Keep component as-is (recommended when semantics matter)
Move unsupported behavior to a different node when possible
Use @boost-ignore for explicit clarity

Skip reason: `has a spread that may carry a translated prop`

A View with a spread ({...props}) Boost can't statically resolve, or that may contain a prop the View wrapper translates (aria-*, tabIndex, id).

Skip reason: `has unresolved ancestor that may render Text`

A component is inside an ancestor React Native Boost cannot statically classify. Boost follows local and imported wrappers through Metro, but unsupported component patterns remain unknown. Boost also treats React Native components other than parity-proven hosts such as View and Text as unknown.

Options:

Keep the default behavior (safest)
Use @boost-force on a specific line you have verified is safe
Refactor the ancestor or component structure so Boost can classify it
Set assumptions.unknownAncestorsDoNotRenderText to true only if that statement is true across the project

Skip reason: `has unresolved runtime parent that may render Text`

A root component can be mounted inside a Text. Boost keeps a root Text wrapper so it can select NativeText or NativeVirtualText. It also keeps a root View with children so the wrapper can reset inherited text context. Android 0.83–0.84 Image uses the same check to select its inline host.

Use @boost-force only when every use of that component has a non-text parent. The project-wide unknown ancestor assumption also overrides this check.

Ignores do not work as expected in monorepos

ignores are resolved from Babel's working directory.

In nested apps, you may need explicit parent paths:

ignores: ['../../node_modules/**'];

Runtime import errors in app code

The plugin injects imports from react-native-boost/runtime.

If you installed react-native-boost as a dev dependency, runtime imports can fail in app builds.

Fix: install it as a regular dependency.

On this page