Debugging
Debugging a Valence app is mostly ordinary web debugging, with one catch: native requests do not appear in a browser’s network panel. http.request runs in the host, not in the page, so DevTools and on-device consoles never see it. traceBridge closes that gap.
Chrome DevTools
Section titled “Chrome DevTools”On Android, a debug build of the host enables WebView inspection. Run it on an emulator, or on a phone connected over USB:
flutter run --debugThen open chrome://inspect in desktop Chrome and click inspect under your app. Profile and release builds never enable this, so a store build does not expose the page to a USB-attached browser. The host does not turn on iOS inspection yet.
For fast edits, add the development server.
Host logs
Section titled “Host logs”The host forwards the page’s console output and its own bridge errors to the system log, in every build:
adb logcat -s flutterLook for webview[error], which includes content security policy blocks, and for bridge error, which names the code and reason, such as E_TOO_LARGE with the size that was refused. Because this covers release builds too, never log tokens, passwords or personal data from the page.
For a launch that is slow or stuck, see Startup diagnostics.
See native requests with traceBridge
Section titled “See native requests with traceBridge”traceBridge reports each finished call() to a listener. It belongs in debug builds only, because the host forwards console output to the system log in release builds too. Use the build-time flag from the next section:
import { traceBridge } from '@getvalence/bridge';
if (import.meta.env.VITE_VALENCE_DEBUG === '1') { traceBridge(({ method, ms, code, url, status }) => { const failed = code || (status && status >= 400); console[failed ? 'warn' : 'debug']('[bridge]', method, url ?? '', status ?? code ?? 'ok', `${ms}ms`); });}It reports the method, the time taken and the BridgeError code. For http.request it adds the origin and path, without credentials, query string or fragment, and the HTTP status. It never carries bodies or headers. A path can still hold an identifier, such as /users/[email protected], so check a screenshot before sharing it. A listener that throws or rejects has no effect on the app’s own call, and with no listener a call does no extra work.
It also sees refusals that happen in the page before anything reaches the host, such as an oversized message or a method the host is too old for. Those never appear in adb logcat.
Writing to the console means one listener feeds every tool on this page in a debug build.
An on-device console for test builds
Section titled “An on-device console for test builds”With no cable, or for testers, add Eruda (MIT). It gives a console, an element inspector and a network panel on the phone. Its logs and panels work under the host’s content security policy without changes. Typing JavaScript into its console does not, because the policy forbids eval.
npm install --save-dev erudaLoad it behind a build-time flag, with a dynamic import so a normal build leaves it out:
import { traceBridge } from '@getvalence/bridge';
export async function startDebugTools() { if (import.meta.env.VITE_VALENCE_DEBUG !== '1') return; const { default: eruda } = await import('eruda'); eruda.init(); traceBridge(({ method, ms, code, url, status }) => { console.log('[bridge]', method, url ?? '', status ?? code ?? 'ok', `${ms}ms`); });}Use your framework’s equivalent of import.meta.env, such as process.env.NEXT_PUBLIC_VALENCE_DEBUG in Next.js. It has to be a value the bundler replaces at build time, so the import is removed from a normal build.
A call that seems not to come back
Section titled “A call that seems not to come back”There are three places a bridge call can be stuck — plus one host state that drops it outright — and they are told apart by different instruments. Work from the outside in, because the cheapest signal rules out the most.
- Check whether the call settled in the page. A correlated
traceBridgetrace without an error code in host mode establishes a successful round trip for that call. An error trace can be a client-side refusal before dispatch; a shim trace makes no native round trip. Missing output is inconclusive unless the listener was installed before the call and its output was captured reliably. Traces have a method name, not a request id: correlate overlapping calls in app-owned instrumentation.connect(),ready()and thelink.initialcallonLink()makes internally use the raw transport and are not traced — so a stuck initial link shows no trace even when everything is wired right. - Check whether the host produced an error reply. A
bridge error <code>: <message>line inadb logcat -s flutteris logged before delivery is attempted. It includes nonce and decoding refusals and does not prove the page received the reply. Successful replies have no corresponding host log line. - Check whether the host is deliberately dropping messages. Under a
mandatory store update the host discards bridge messages without replying.
It logs once per state:
bridge: dropping messages, a store update is required (§2.5); calls will not be answered. The blocking screen is visible, and calls made by the page remain pending. A repeated probe cannot bypass that state. - Use a known non-mutating read as a separate probe.
app.state,app.info,sync.statusanddata.gettake no sync lease and start no sync. A successful probe establishes that its own request/reply path worked at that later time; it cannot rule out a lost or stalled earlier request. Check app/plugin method semantics before repeating any other call. Do not replay writes, native actions or network requests merely because an observer timed out: the first call may already have taken effect.
A stall seen through a wrapper whose own deadline is shorter than the deadline of the tool it wraps reports a timeout with the inner diagnostic suppressed, so it does not locate the cause. Record both deadlines and the last completed phase. A painted page, live process and absent ANR do not locate the failed dispatch/reply/observer boundary. Keep the failed observation and the successful retry as separate records: a retry that works does not retract the one that did not, and collapsing them loses the only evidence that something intermittent happened.
Which tool to use
Section titled “Which tool to use”| Situation | Use |
|---|---|
| A call that never seems to return | The three places it can be stuck |
| Developing on an Android emulator or a phone with a cable | Chrome DevTools |
| A native request fails or is refused | traceBridge, which sees everything, or adb logcat -s flutter, which sees what reached the host |
| A tester’s phone with no cable | Eruda in a test build |
| A blank screen or a slow launch | adb logcat -s flutter and Startup diagnostics |
| Update, rollback or trial behaviour | Local testing |