Troubleshooting

Start with check#

Run:

mockspace check --project <dir>

Fix every reported missing source path, state URL, invalid action, and edge endpoint. The output also prints the exact app URL and start command used by this workspace. Confirm those match the process you intend to capture.

No config is found#

The --project directory must contain .mockspace/config.mjs, .mockspace/config.js, mockspace.config.mjs, or mockspace.config.js. Run the command from the application root or pass the correct nested directory.

Mockspace has no init command. Follow Set up with your agent or the installed mockspace-setup skill to inspect the application and create truthful declarations.

The viewer opens the wrong app#

Another process may own the configured app.url, especially a common development port. Inspect the port owner, stop the stale process, and start the current checkout with the command printed by check.

For branch-isolated capture, start that app on its own port and pass mockspace build --app <url>. The flag changes the capture target without rewriting the workspace's canonical config.

Every frame shows sign-in#

An unhandled session endpoint or boot-time mock layer can redirect the authenticated shell before the intended page renders. Confirm that the application's development auth mechanism is enabled, every layout request is handled, and config auth.cookies contains only the noninteractive cookies the app supports.

Some fixture interceptors initialize only when the dev server boots. If the problem began after editing fixtures, restart the application rather than only refreshing the canvas.

Do not automate a real OAuth round trip as a hidden capture step. Prepare a supported development gate or fixture path in the application.

A frame is loading or an error card#

Open the declared state URL directly through the running application and inspect its logs. A third-party key that is present but invalid often throws where an empty value would select the application's unavailable fallback. Put every capture-affecting environment value in config app.env.

Build reports frames that never became quiet and pages that kept the network active. Stabilize the application, or mask only a value whose purpose is to change continuously with diff.ignoreSelectors. Do not mask real product behavior to make the build green.

Two states look identical#

Confirm that each URL selects a different fixture world and that the page's client requests carry the selector. Check for a fallback that invents healthy data after the fixture intentionally returned empty or failed.

Compare rendered frame text or pixels, not server HTML or status alone. Client-rendered pages often return the same loading shell for every URL.

Delete a state if it has no distinct behavior or review purpose. Duplicate labels do not create coverage.

An action state does not open#

Each act step uses one action verb. Prefer an accessible-name selector; an icon button may need its aria-label rather than text. Add expect for a dialog or overlay so the capture fails when the trigger matches but the expected UI never appears.

Use reachedBy only to connect a control in an inert frame to an already captured state. It does not perform the action during capture.

A source edit is read-only over MCP#

Read get_edit_policy, then call check_manageable_files for the exact paths. A file must be declared by the workspace and satisfy the local ownership rule. Do not bypass a denial by using a broader path or another connection.

Hosted direct MCP has no local file tools. Use the matching checkout and supported local relay when source context is required.

Login or publish is refused#

Run mockspace whoami --service <origin> and check the expiry. Sign in again if needed. An explicit token or environment token takes precedence over the saved login, so remove or correct a stale override before assuming the personal login failed.

A 404 for a private draft may mean the signed-in identity is not its owner. A publish also requires a completed static build and a credential permitted to write.

Search finds nothing#

Try fewer terms or a command name such as build, mcp, or visibility. Search covers published documentation only; draft content and private project data are deliberately absent. If the search index cannot load, browse the grouped documentation navigation and reload the page.