Skip to main content

EFS troubleshooting

This page covers user-visible EFS failures. It stays at the product and CLI level.

morphcloud efs is not found​

Confirm the EFS client is installed:

uv tool install morphcloud-efs-client

If you just installed or upgraded it and your shell still finds an older command, refresh the shell command cache:

hash -r

Then check:

morphcloud efs --help

Install fails with private package access errors​

In Morph-managed environments, private package access is preconfigured, but you still authenticate package install with your Morph API key:

export MORPH_API_KEY="morph_your_api_key"
uv auth login https://simple-index.svc.cloud.morph.so --token "$MORPH_API_KEY"
uv tool install morphcloud-efs-client

If this still fails, confirm the API key is valid for the Morph account or organization you are using.

If the package cannot be found at all, use a supported Morph-managed environment or confirm that package access was configured for the external host before install.

I do not see an update notice​

Update notices are shown only by interactive morphcloud efs commands when your installed client is older than the latest published client.

This command is handled by uv, so it does not show Morph EFS update notices:

uv tool install morphcloud-efs-client

To upgrade directly, run:

uv tool upgrade morphcloud-efs-client

If you are already on the latest version, no notice is shown. Notices are also hidden for --json commands and non-interactive scripts.

EFS commands fail with auth or profile errors​

Set the Morph profile after installing:

morphcloud profile set default --api-key "$MORPH_API_KEY"
morphcloud profile use default

Then retry:

morphcloud efs ls

Mount fails before starting​

EFS mounts require a Morph-managed Linux VM/devbox, or an equivalent FUSE-capable Linux host.

The host must have Linux FUSE support, /dev/fuse, fusermount3, and permission for the current user to create FUSE mounts. EFS does not install OS packages or run sudo.

If the host is unsupported, the client fails fast with a clear Morph EFS message. Move to a supported Morph-managed environment or prepare FUSE support on the host before mounting.

See Mount requirements.

The mount command is slow to return​

Mount startup can take a moment because EFS prepares the mount before returning. The command returns only after the mount path is ready:

morphcloud efs mount shared-files

Expected success output includes the mounted filesystem name and mount path, followed by a note that the mount is active in the background.

I cannot find the mounted path​

If you did not pass an explicit path, EFS mounts at:

~/morph-efs/<filesystem>

For example:

ls ~/morph-efs/shared-files

If you chose a path explicitly, inspect that path instead:

morphcloud efs mount shared-files /tmp/shared-files
ls /tmp/shared-files

Reads do not show the data I just wrote​

Flush writes before immediately verifying them from another process or before unmounting:

echo hello > ~/morph-efs/shared-files/test.txt
sync
cat ~/morph-efs/shared-files/test.txt

Another host cannot see my file​

Confirm both hosts are mounted to the same EFS filesystem name in the same Morph context:

morphcloud efs get shared-files
morphcloud efs usage shared-files

On the writing host, flush the file before checking from the other host:

sync

On the reading host, check the mounted path for the same filesystem:

ls ~/morph-efs/shared-files
cat ~/morph-efs/shared-files/test.txt

If two processes write the same file at the same time, use an application-level coordination pattern before treating the result as reliable.

TUI cannot browse files​

File browsing requires an active mount. Mount the filesystem first:

morphcloud efs mount shared-files
morphcloud efs tui shared-files

In the TUI, use the browse action after the mount is active.

Multiple filesystems are visible in the TUI​

If more than one ready filesystem is visible, pass the filesystem name:

morphcloud efs tui shared-files

Dashboard does not open a browser​

Ask the CLI to print the dashboard URL:

morphcloud efs dashboard shared-files --no-open

If you are in a headless environment, open that URL from a browser that can reach Morph EFS.

Dashboard auth fails​

The dashboard uses your current Morph profile to create a temporary browser link. Confirm the same profile works for normal EFS commands:

morphcloud efs ls
morphcloud efs dashboard shared-files

If the dashboard link expires, run the dashboard command again to create a fresh link.

Unmount does not find the expected filesystem​

Use the filesystem name or id you used for create, get, or mount:

morphcloud efs get shared-files
morphcloud efs unmount shared-files

If you mounted at an explicit path, the unmount command still uses the filesystem name or id:

morphcloud efs unmount shared-files

Delete asks for confirmation​

Use --yes for non-interactive cleanup:

morphcloud efs delete shared-files --yes

Unmount active mounts before deleting when possible.

Deleted filesystem still appears briefly​

Delete marks a filesystem for cleanup. Cleanup finishes asynchronously, and active mounts can delay cleanup. Unmount active mounts first, then check again after cleanup has had time to converge:

morphcloud efs unmount shared-files
morphcloud efs ls