Linux Troubleshooting

Known issues and fixes on Linux.

Files owned by an unknown user after using a local folderCopy Anchor Link

When you start a workspace from a local folder and devcontainer.json sets remoteUser or containerUser, Devsy changes the folder's ownership to that user so the container can write to it. On the host the owner then shows as an unknown user. After the workspace stops, restore it:

sudo chown -R $(id -un):$(id -gn) .

Local folders suit early work. Once the devcontainer works, push it to a Git repository and use that instead.

SSH host login shellsCopy Anchor Link

The SSH provider supports Bash, Zsh, and Fish login shells on Linux. Agent installation runs through the host's executable /bin/sh; interactive terminals and environment probing continue to use the account's configured shell. The workspace container's shell is configured separately.

Dockerless containers are a separate bootstrap case: before their image filesystem is built, core can use the fixed /.dockerless/bin/sh bundle when DOCKERLESS=true, /bin/sh is not executable, and that bundled shell is executable. /bin/sh remains preferred when available. This does not change the SSH host prerequisite above.

The host needs standard bootstrap tools, including mkdir, mktemp, head with -c, wc, chmod, mv, and rm. A download uses curl or wget; when neither is available, Devsy can transfer the agent over the SSH connection. The agent directory must permit execution and either be writable by the account or allow noninteractive privilege escalation.

If startup reports command not found: sh -c, check the installed SSH provider version and its release notes for the POSIX bootstrap fix. Changing the account's shell is unnecessary. Both the external OpenSSH client and the built-in SSH transport use the same bootstrap launcher; switching transports does not repair a missing /bin/sh or a restricted account.

For locked-down accounts, ask the administrator to permit /bin/sh and the required tools, provide a writable executable agent directory, and check forced-command restrictions. Keep noninteractive shell startup output off stdout: it carries the bootstrap protocol and the live SSH tunnel. Send diagnostics to stderr and limit banners and prompts to interactive sessions.

Fish startup configurationCopy Anchor Link

Anything in config.fish runs on every fish -c call, which can interfere with devsy agent workspace up. Move your customizations inside the if status is-interactive block:

if status is-interactive
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
    # customizations
end

SELinuxCopy Anchor Link

With SELinux, a mounted volume can fail with "Permission denied" even when ownership is correct. Add :Z to the volume:

{
    "workspaceMount": "",
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "runArgs": [
        "--volume=${localWorkspaceFolder}:/workspaces/${localWorkspaceFolderBasename}:Z"
    ]
}

ENAMETOOLONG when opening a workspace in VS CodeCopy Anchor Link

Some distributions have a very long PATH, which makes the SSH connection string too long. Set the SSH binary explicitly in VS Code. See issue #1045.

Docker permission denied or daemon unreachableCopy Anchor Link

If devsy workspace up fails with a permission error on docker.sock, add your user to the docker group and log in again:

sudo usermod -aG docker $USER

If the daemon is not running, start it:

sudo systemctl start docker

PodmanCopy Anchor Link

Rootless socketCopy Anchor Link

Rootless Podman uses the socket $XDG_RUNTIME_DIR/podman/podman.sock. If Devsy cannot connect, start the user socket:

systemctl --user start podman.socket

Or point Devsy at it:

devsy provider set podman --option PODMAN_HOST=unix:///run/user/$(id -u)/podman/podman.sock

podman composeCopy Anchor Link

podman compose hands off to an external provider, either podman-compose or a standalone docker-compose. Install one:

sudo apt-get install -y podman-compose

Install it on the host that runs Podman to support Compose-based workspaces. If scripts inside the workspace container call docker-compose or podman compose, install those tools in the container too.

BuildKit syntaxCopy Anchor Link

podman build uses buildah, so Dockerfiles with the # syntax=docker/dockerfile:1 line or RUN --mount fail. Remove the syntax line and avoid BuildKit mounts.

Volume permissions in rootless modeCopy Anchor Link

Rootless Podman maps user IDs, so files created in the container can appear owned by nobody on the host. With SELinux, use :Z as above. Without it, fix ownership:

podman unshare chown -R $(id -u):$(id -g) /path/to/volume