Skip to main content

Troubleshooting UI capture​

View as Markdown
FreeTeamsScaleEnterpriseSelf-HostedDedicated

Each entry below is a symptom, its cause and what to do. When the SDK reports a KUI_E_ code in the browser console or to onError, UI Capture errors and warnings has that code's own section. The app's capture status, on the dashboard's setup card or over the API, is the first thing to read: it says whether recordings arrive and whether they have become flows.

Setup​

The console shows 403 and "this API key is not a UI ingest key"​

Cause: apiKey holds a personal access token or another kind of Keploy key. The ingest endpoint takes only an ingest key.

Fix: Create an ingest key for the app, in the dashboard or with POST /client/v1/apps/<appId>/ui/ingest-keys, and pass it as apiKey. See Ingest keys and environments.

The console shows 401 on the posts to /ui/v1/ingest​

Cause: The key is missing, unknown, expired or revoked, or its app was deleted. A revoked key is refused within about 30 seconds.

Fix: Create a new ingest key for the app and use it. The capture has ended with KUI_E_INGEST_KEY_REJECTED; a new key takes effect on the next page load.

The console shows 404 or 405 on the posts​

Cause: endpoint is wrong: the route is <api-server>/ui/v1/ingest.

Fix: Use https://api.keploy.io/ui/v1/ingest on Keploy Cloud, or your API server's URL followed by /ui/v1/ingest. See KUI_E_INGEST_ENDPOINT_NOT_FOUND.

Nothing arrives, and the console shows a CORS or Content-Security-Policy error​

Cause: Either the browser refused the request before any status reached the SDK, because the endpoint's path is outside /ui/v1/ on another origin, or the page's Content-Security-Policy does not allow the endpoint in connect-src. The SDK reads either as a network failure: it keeps retrying, and never calls onError.

Fix: Check the endpoint, and allow its origin in connect-src. See Content-Security-Policy and workers.

Creating a key asks you to "Confirm it's you"​

Cause: Creating or revoking an ingest key in the dashboard needs a recent sign-in.

Fix: Click Sign in again and sign in; the dashboard then creates the key. See Create an ingest key.

Sessions​

Capture status stays at NO_SESSIONS​

Cause: No recording has reached the app. Usually init does not run in the browser, the key is not this app's, or the browser sends Do Not Track or Global Privacy Control.

Fix: Open the app with the browser's developer tools: the SDK posts to /ui/v1/ingest every few seconds while you use the page. A KUI_E_ code in the console says why it does not. See Check that it works.

Sessions arrive in another app​

Cause: A page records into the app of the key it sends. The SDK sends no app of its own, so a key made for another app is accepted, and its recordings go into that app, with no error.

Fix: Build the page with an ingest key of the app you mean. The key list (Ingest keys on the setup card, or listUIIngestKeys) shows each key's prefix, the start of the key, so you can tell which key a page ships. Keep each environment's visits apart with an app per environment.

Some visitors never show up​

Cause: The SDK records nothing for a browser that sends Do Not Track or Global Privacy Control, as it does by default, and Brave and DuckDuckGo send Global Privacy Control by default. A sampleRate under 1 leaves page loads out too.

Fix: Nothing, for the privacy signals: those visitors said no. See Visitors' privacy signals and Sampling.

Each page of a site whose links load pages is a session of its own​

Cause: A session is one page load of your app with its in-app navigation. A link that loads a page starts a new page, and with it a new capture and a new session. So on such a site, every journey is one page long.

Fix: This is how capture works on such a site; a single-page app keeps one session across its route changes. See What a session is.

KUI_E_SESSION_CONFLICT after you completed a visit with its tab open​

Cause: POST /ui/v1/sessions/<id>/complete ended the session on Keploy's side, and the tab went on recording into it. Its next batch is refused with 409, and the capture ends with KUI_E_SESSION_CONFLICT; with continuous: true and the SDK's own session ids, a new session starts at the visitor's next interaction instead.

Fix: Stop the capture before you complete its session: close the tab, or call KeployCapture.stop() and wait for it to resolve, as the sample shops' scripted visits do. See End a visit at once.

A tab that comes back after 30 minutes stops recording​

Cause: A tab can send no batch for more than 30 minutes while its session is still open: on a computer that slept, or with a maxSessionDuration longer than 30 minutes (by default a session ends after 10). By then Keploy has completed the session, so the tab's next batch is refused, and its capture ends with KUI_E_SESSION_CONFLICT.

Fix: Set continuous: true: with the SDK's own session ids, the capture then starts a new session at the visitor's next click, tap or key press. See A tab that comes back after 30 minutes.

Flows​

Sessions arrive, but no flows appear​

Cause: A visit becomes flows 30 minutes after its last activity. Until then capture status says RECORDING.

Fix: Wait, or end the visit at once with POST /ui/v1/sessions/<session id>/complete: its flows follow within a minute or two. See End a visit at once.

Capture status says FLOWS_READY while some visits are still COMPLETED​

Cause: The state is FLOWS_READY as soon as the app has any flow, whatever its other sessions are doing. Visits finished later are still being processed.

Fix: To wait for particular visits, read their sessions: sessionsByStatus counts every state, and recentSessions gives each recent session's status by its sdkSessionId. Check capture in CI waits that way.

A flow named Navigate on /…, with one step​

Cause: A page that was opened and left untouched still makes a flow, of one step: arriving on the page. The texts for NO_FLOWS suggest otherwise. The setup card says the visits had no "click, typing or navigation to make a flow from", and capture status says "a page that is only loaded has no flow". Such a page makes this one-step flow.

Fix: Nothing to fix: the flow records that a visitor arrived on the page and did nothing there. See Read the flows.

Capture status says NO_FLOWS or ALL_FAILED​

Cause: NO_FLOWS: the app's visits were processed, and none made a flow. ALL_FAILED: every finished visit failed to be processed; a visit is retried for about two hours first.

Fix: Record a fresh visit that uses the app. If it fails again, contact Keploy support with the sdkVersion that recentSessions shows. See Capture status.

A single-page app's visit makes one flow, on the page it landed on​

Cause: @keploy/capture-sdk 3.0.1 records no route change made by script, so every step of the visit belongs to its first page. 3.1.0 records each route change, and each route is its own flow.

Fix: Upgrade to 3.1.0. recentSessions in capture status shows each session's sdkVersion. See Single-page apps and navigation.

The first page's first requests are missing​

Cause: The SDK records the page's requests only once it has loaded rrweb, which your bundler puts in a chunk of its own. Until then fetch and XMLHttpRequest are still the browser's own, so a request made in that window goes out as without the SDK, and is not recorded.

Fix: Call init as early as you can, from a module your app imports before its own code. That narrows the window; nothing closes it. See Start capture before your first call.

Bodies​

A body readsWhySee
[Response body not read by the page]Your app never read that response's body, so the SDK did not either. A replay sends this text.How the SDK reads a body
...[truncated] at its endIt was longer than maxBodySize, or it failed part-way.Large bodies
[UNPARSEABLE_BODY_NOT_REDACTED]It was JSON longer than maxBodySize: a cut JSON body cannot be redacted, so it is not kept.Large bodies
[Response body too large: N bytes]Its Content-Length was over maxBodySize, so it was not downloaded.Large bodies
[Body cut: K of N characters kept, unverified]The page has no body worker, so bodies are redacted on the main thread up to 64 KiB; or the page left, or the capture stopped, with bodies still in the worker; or, with 0 kept, the bodies held for redaction were at their limit.Redaction off the main thread
[Body not captured: …]The SDK could not redact it, so it kept none of it. This line follows [Body cut: 0 of N …] and says why.Redaction off the main thread
[MASKED]privacyMode: "strict" or privacy.maskNetworkBodies: true records every body that way.Mask every body
[Blob: …], [Binary: …], [ReadableStream], [Unreadable body]The body was not text the SDK reads.Large bodies

Build and Content-Security-Policy​

KUI_E_DOM_RECORDER_UNAVAILABLE​

Cause: The browser could not load rrweb: a page with no bundler and no import map for rrweb, a Content-Security-Policy that blocks its chunk, or a deployment that dropped it. The capture ends before anything is sent.

Fix: See KUI_E_DOM_RECORDER_UNAVAILABLE, and No bundler for the import map.

parcel build fails: the buffer polyfill is not installed​

Cause: rrweb's build reads Node's Buffer, and Parcel does not install the polyfill itself when CI is set. The build stops with Node builtin polyfill "buffer/" is not installed, but auto install is disabled.

Fix: npm install buffer. See Parcel 2.

KUI_E_BODY_WORKER_UNAVAILABLE, with "part":"worker"​

Cause: The page cannot run the SDK's body worker: esbuild does not emit it, webpack 4 cannot, a Content-Security-Policy blocks it, or your assets are served from another origin. Bodies over 64 KiB are then recorded cut.

Fix: Under esbuild, copy node_modules/@keploy/capture-sdk/dist/body-worker.js beside your bundle; allow worker-src 'self'; serve the worker from the page's origin. See Where there is no body worker.

Strict mode​

KUI_E_PRIVACY_CONFLICT​

Cause: privacyMode: "strict" is set with privacy.maskNetworkBodies: false, which asks for the bodies strict leaves out. A privacy object built from defaultPrivacyConfig() carries that false.

Fix: Remove maskNetworkBodies, or use "balanced". See KUI_E_PRIVACY_CONFLICT.

KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE​

Cause: Strict could not load its attribute allow-list, a chunk of its own, so it recorded nothing.

Fix: Deploy every chunk your build emits, or serve the package's dist/ as it is. See KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE.

A visitor's data shows up under strict​

Cause: Strict still records what describes the page's structure, as written: URL paths, id and class values, a field's name, and data-testid values.

Fix: Never build a data-testid, an id or a path from a visitor's data, or block that element with privacy.blockSelectors. See What strict records, and what it doesn't.

Agents and the API​

The UI capture tools are missing from the MCP server's tools/list​

Cause: The server runs in tool-search mode: tools/list shows only its search and setup tools.

Fix: Fetch the tools you need by name with get_tool_schema, and run them with invoke_tool. See MCP tools.

Agents get 401 after weeks of working (keploy mcp-install)​

Cause: The token keploy mcp-install mints expires after 90 days. Run again, mcp-install hands out the same token from ~/.keploy/mcp.yaml without checking that it has expired.

Fix: Run keploy mcp-install --rotate, then configure again every agent that used the old token. See Connect your agent.

429 RATE_LIMITED​

Cause: The API key made more than 100 requests in a minute, or the server's queue of journey plan computations is full.

Fix: Wait, then retry: Retry-After seconds over REST; over MCP, which shows no headers, the 10 seconds a refused uiJourneys names, otherwise a minute. Poll capture status at most once a minute. See Waiting and polling.

deleteApp is refused​

Cause: Deleting an app needs the admin scope. A token from an MCP OAuth sign-in never has it, and only organization admins can give it to an API key.

Fix: Delete the app with an admin's API key that has the admin scope. See Delete an app.

An ingest key, or a service-account key, is refused by the REST API​

Cause: An ingest key can only post recordings: the REST API refuses it with 403 INSUFFICIENT_SCOPE, and the MCP server does not accept it. A service-account key bound to UI_READER only reads: it cannot create or delete apps, or list, mint or revoke ingest keys.

Fix: Use a personal access token with the scope the operation needs. See Errors an agent should handle.

Dashboard​

A panel says the figure "was never measured"​

Cause: The Flow Graph panel on the Flows tab and the Coverage tab are not served yet. Each says that the server does not expose it and that the figure was never measured: it is not zero. The Generated Test panel on a flow's page says the server does not expose the test's source.

Fix: For the flow graph, use GET …/ui/flow-graph or the MCP tool uiFlowGraph. See The flow graph.

A test run from Generate Test stays pending​

Cause: Generate Test creates a UI test run and marks the flow Test generated. In the dashboard's own words: "No runner ships in this release, so the run stays pending until one does." Replaying journeys as Playwright tests is in beta, and the keploy ui commands, its runner keploy ui run among them, are not in a release build yet.

Fix: None yet. See Replay (beta).

The Journeys tab is empty​

Cause: A journey plan reads the app's sessions that started in the last 30 days and have been processed. No sessions in this window means there are none; No session has a journey yet means sessions were read but none could be counted yet.

Fix: Record a visit and wait until capture status says FLOWS_READY, then reload the page. Over the API, uiJourneys with refresh=true computes a new plan at once; it needs the write scope and testgen:run on the app. See Journeys and replay (beta).