Help · LayerFS docs

Help

Fixes for the refusals you'll meet, answers to common questions, and the words LayerFS uses.

Troubleshooting

A refused call throws a LayerFSError whose code says what happened. Look before you act: nothing is ever retried for you. Find the code below.

Unsupported Every fs, branch or project call fails.

Why: The process isn't on Linux, or the Store isn't on a local ext4, xfs or btrfs filesystem shared with the daemons.

Fix: Run your agent's process in a Linux container that mounts the Store's volume. See Supported platforms.

InvalidInput "Store calls need options.storePath" or "deploy.… is not configured".

Why: An environment variable is missing for this process.

Fix: Set LAYERFS_STORE_PATH, LAYERFS_HOME, LAYERFS_DOCKER, LAYERFS_IMAGE, LAYERFS_VOLUME and LAYERFS_DAEMON, the same for every process of a run.

Exists project.init is refused.

Why: The project was already initialized in this LAYERFS_HOME.

Fix: Nothing to fix: use it. new LayerFS(name) finds it.

Busy sandbox.create is refused.

Why: Another create for the same project was running.

Fix: Create Sandboxes one at a time, then start parallel work. Nothing was created, so create again once the other finishes.

Failed sandbox.create fails with detail.removed.

Why: The container never became ready, for example a daemon that exits at startup. It has been removed.

Fix: Read detail.log (the last daemon log lines, also in the message) and fix the cause before creating again.

Unknown Every sandbox.create for the project is refused.

Why: An earlier create's outcome is unknown, so LayerFS won't risk a second install.

Fix: A person cleans up what the message names (containers on the volume, then create.intent). Don't retry blindly.

Conflict A write or sandbox.commit is refused.

Why: Someone changed the same path on the Branch first. Nothing was committed.

Fix: Read both sides. From a Workspace, fix the markers and commit again: see Merge and conflicts.

Dirty sandbox.unmount is refused.

Why: The Workspace has changes that aren't committed; detail.changed lists them.

Fix: Commit them, so the step is recorded. Pass discard = true only to abandon them.

MountsActive sandbox.close is refused.

Why: A Workspace is still mounted in the Sandbox.

Fix: Commit or discard, unmount every Workspace, then close.

NoMatch fs.edit is refused (or AmbiguousMatch).

Why: oldText isn't in the file, or appears more than once.

Fix: Read the file as it is now, then include enough surrounding lines to match exactly once.

TooLarge A write is refused before anything is sent.

Why: Paths, edit texts and message together passed 65,519 bytes.

Fix: Make a smaller call, or do the change as one command in a Workspace.

exec hangs sandbox.exec doesn't return.

Why: It waits for everything holding its output, including background processes, and has no timeout.

Fix: Wrap commands in timeout and send a server's output to a file: node server.js >/tmp/server.log 2>&1 &.

stale view A Workspace doesn't show an fs write.

Why: A Workspace shows its Branch as it was at mount.

Fix: Mount a new Workspace to see it. The next Commit merges it in anyway.

To see what a daemon did, save its container's log before you close the Sandbox:

docker logs "$(cat "$LAYERFS_HOME/_sandboxes/dev/container")" > daemon-dev.log 2>&1

FAQ

Is the SDK on npm?

Not yet. @layerfs/sdk is a private package in the LayerFS repository; link sdk/js into your project. The install prompt has your agent do it.

Does LayerFS replace Git?

No. Your .git folder is part of the tree like any other file, so Git works inside a Workspace as usual. LayerFS records every step underneath it, including the files Git ignores.

Are ignored files and node_modules really saved?

Yes. Init captures everything, and a Commit saves everything in the Workspace. Repeated content is stored once, so many copies cost little.

Can agents on different machines share one Store?

Not today. Every process that opens a Store must share one Linux kernel and a local filesystem. Agents on one host, each in its own Sandbox, share it fine.

Does mounting copy my project?

No. A mount binds the committed tree and creates only the Workspace's small overlay database. Content loads as it's read.

Does LayerFS run or time out my commands?

sandbox.exec launches bash -c in the container and returns its exit code and output. The LayerFS daemon only serves files; it doesn't supervise, time out, or commit for you.

Should I commit a failed step?

Yes. Commit after every Bash call with a message like "step 12: npm test (exit 1)", so the Branch shows what each step did. A step that changed nothing just answers UpToDate.

How do I undo a step?

Find the Commit before it with branch.list_commits and fork a new Branch from it. The bad step stays in history; nothing is rewritten.

Is my data safe if the machine loses power?

Not guaranteed. The Store runs without waiting for the disk, so a power loss or OS crash can lose recent history. See Durability.

Does Windows work?

Not for Store calls; they need Linux. Run your agent in a Linux container or VM that holds the Store on a local filesystem.

Glossary

Branch: A named line of Commits where agents work. Forking one copies no files.
Commit: One saved change on a Branch: every fs write, every sandbox.commit, every merge. Immutable.
Conflict: The refusal when two writes changed the same path. Nothing is committed.
daemon: The LayerFS process in each Sandbox. It serves Workspaces and opens the Store directly.
Disposable: The Store's one profile: SQLite WAL with synchronous=OFF. Durability is not claimed.
fork: Starting a Branch from a ref. Records where it starts; copies nothing.
Layer: One published state of main. Init makes main @ L0; each publish adds one.
/.lww: A file of gitignore-style patterns. Matching paths changed on both sides keep the newer version instead of conflicting.
main: The project's published line of Layers. Read-only; changes only by branch.publish.
merge base: The newest state both sides of a merge share; a three-way merge compares each side with it.
overlay: A Workspace's own small database of changes on top of the committed tree. Deleted at unmount.
project: One source tree under LayerFS, with its own Store.
publish: Making a Branch's Commit main's next Layer. It overwrites; merge main in first to keep others' work.
ref: What a read names: main, a Branch name, a Commit id or a Layer id.
Sandbox: A named container running one daemon, bound to one project and image. It holds Workspaces.
Store: The one SQLite file holding all of a project's committed state, on a shared local volume.
UpToDate: The answer when a write changed nothing: no Commit is made.
Workspace: A complete, writable view of a Branch mounted in a Sandbox, at /workspaces/N.