Troubleshooting

Start with the composed profile and the engine status. Most installation issues are either a package that was installed but not mounted, or a profile that has not been restarted.

The installer says “declares no dsh.bundle”#

dsh: warning: dsh-filesnap declares no dsh.bundle — installed as a plain
dependency, not a profile layer

You have a version before 0.2.2. Since 0.2.2 the package ships a dsh.bundle, so dsh plugin add mounts it by itself and this warning no longer appears:

$ dsh plugin --profile web add dsh-filesnap@latest

On the older version the plugin has to be mounted by hand — add this row to ~/.dsh/profiles/web/cordis.patch.yml (or the headless file for --profile headless):

- insert:
    - id: filesnap
      name: dsh-filesnap

Delete that row before upgrading to 0.2.2. The bundle supplies the same row and the loader refuses two entries with one id — see the next section.

dsh fails to start with `duplicate loader entry id: filesnap`#

dsh: plugin tree failed to load: failed to apply loader entry include
(cordis:include): duplicate loader entry id: filesnap

The profile has two filesnap rows: the one the 0.2.2 bundle now supplies, and the one an earlier version's instructions had you add by hand. The loader does not merge or override rows by id — a second insert carrying an existing id is an error, and the whole plugin tree refuses to load.

Open ~/.dsh/profiles/<profile>/cordis.patch.yml and delete the hand-added block:

- insert:
    - id: filesnap
      name: dsh-filesnap

Leave any other rows in that file alone. Start dsh again; --dump-config should now list name: dsh-filesnap exactly once, under the # == dsh-filesnap layer.

The plugin does not appear to load#

Inspect the configuration that actually boots:

$ dsh --profile web --dump-config | grep -A 2 filesnap

You should see the id and package name. If not:

confirm that the package was installed into the same profile;
check that insert contains a list of rows, including both indentation levels shown above;
restart the profile after editing its patch;
inspect startup stderr for configuration validation failures.

Unknown config keys and invalid values fail at load. Remove the invalid field or compare it with the configuration table.

The filesnap command is unavailable#

The platform binary arrives as an optional dependency of the filesnap npm package. Check the copy inside the active profile:

$ ~/.dsh/profiles/web/node_modules/.bin/filesnap --version

Prebuilt packages exist for Linux, macOS and Windows on x64 and arm64. If the launcher is absent:

check whether the package manager was run with optional dependencies disabled;
reinstall dsh-filesnap in the profile;
verify the active Node version satisfies ^22.19 or >=24;
for another platform, build/install filesnap-cli with Cargo and set the plugin's command config to that executable.

For a subprocess provider whose execution environment is another machine, set command to a bare name that the provider can resolve through its own PATH.

`/rewind` lists no points#

A point exists only after a turn entered and its capture completed successfully.

Run at least one complete agent turn before listing.
A deployment decision that rejects a step deliberately produces no capture.
A failed capture is omitted rather than displayed as a point that cannot be honored; inspect stderr for the filesnap error.
Confirm the session has a real working directory. A workspace-less agent cannot bind a filesnap session to a directory.

Use the engine log when you know the session id:

$ ~/.dsh/profiles/web/node_modules/.bin/filesnap log --session <session-id>

The browser action is missing#

The same profile row mounts the host and exposes the ./client bundle. Check:

the plugin appears in --dump-config;
the installed package contains lib/client.js;
the package.json contains exports["./client"] and dsh.client;
the web profile was restarted after installation;
startup logs contain no client-modules: client bundle not found message.

When developing from a checkout, build both surfaces:

$ npm run build
$ npm run build:client

build:client requires a built DeepSeek Harness checkout. Follow CONTRIBUTING.md for the link step.

`/rewind` in the web composer does not navigate#

This is a current host-command limitation. The command reports the new child session id; open that session manually. The per-turn browser action uses the deployment's fork API and navigates automatically.

A session refuses to open with "unknown to this harness"#

Failed to load history: … session "…" contains event type "filesnap/point"
(seq N) unknown to this harness and not marked ignorable; refusing to
interpret the log

The log holds this plugin's events and the reader that opened it did not have the plugin's type declaration. Nothing is lost; the log and the snapshot data are intact. Two causes, told apart by whether the plugin is installed:

It is not installed. Reinstall and mount dsh-filesnap in the profile that opens the session.
It is installed and running, and dsh was started with pnpm dsh. A source launch resolves the harness's packages to src/ while the plugin's import resolves to lib/, so the declaration lands on a different module instance than the reader consults. Start dsh from the built CLI instead:
```
$ node apps/cli/lib/bin.js web
```
or use an npm-installed @deepseek-ai/dsh. Both resolve every package to lib/, and the same session opens.

Why the plugin cannot simply mark its events ignorable is in the architecture note.

Some files are not protected#

Ask the current workspace rather than guessing:

/rewind status

The report names unprotected paths and reasons such as size, readability or file type. Also check .filesnapignore; its exclusions apply symmetrically to capture, restore and deletion.

Shell writes outside the workspace or outside the bounded recent-change scan are covered only if the same path is observed through ctx.fs.

Storage use is higher than expected#

/rewind status separates workspace records from shared blobs. Unchanged blobs are shared across points and sessions, so the total is not a sum of full copies.

The plugin does not yet wrap the engine's lifecycle commands. They are available inside the profile:

$ ~/.dsh/profiles/web/node_modules/.bin/filesnap doctor --workdir .
$ ~/.dsh/profiles/web/node_modules/.bin/filesnap delete --session <session-id>
$ ~/.dsh/profiles/web/node_modules/.bin/filesnap gc

doctor clears interrupted-operation debris. delete permanently removes the selected session's snapshot records from the filesnap store; run it only when those rewind points are no longer needed. gc reclaims blobs that are already unreachable. None of these commands changes the project or Git repository.

Collecting a useful bug report#

Include:

dsh-filesnap and dsh versions;
operating system and architecture;
active profile name;
the --dump-config row, with secrets removed;
startup stderr and the failed command's output;
/rewind status output when the issue is about coverage or storage;
whether the problem occurs in web, headless or both.

Do not attach private source files or session logs without checking their contents. Report security problems through SECURITY.md.

Edit this page ↗Get started →