Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

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.

On Android, a debug build of the host enables WebView inspection. Run it on an emulator, or on a phone connected over USB:

Terminal window
flutter run --debug

Then 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.

The host forwards the page’s console output and its own bridge errors to the system log, in every build:

Terminal window
adb logcat -s flutter

Look 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.

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.

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.

Terminal window
npm install --save-dev eruda

Load it behind a build-time flag, with a dynamic import so a normal build leaves it out:

src/debug.ts
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.

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.

  1. Check whether the call settled in the page. A correlated traceBridge trace 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 the link.initial call onLink() makes internally use the raw transport and are not traced — so a stuck initial link shows no trace even when everything is wired right.
  2. Check whether the host produced an error reply. A bridge error <code>: <message> line in adb logcat -s flutter is 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.
  3. 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.
  4. Use a known non-mutating read as a separate probe. app.state, app.info, sync.status and data.get take 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.

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