Troubleshooting
Known issues and workarounds. For Linux-specific problems, see Linux troubleshooting.
Utilities not found in PATH
If Devsy Desktop cannot find tools such as docker in your PATH, start it through your shell. On macOS:
#!/usr/bin/env sh
exec "$SHELL" -lic 'exec /Applications/Devsy.app/Contents/MacOS/Devsy'Port forwarding does not work without an IDE
Port forwarding needs an open SSH session. With --ide none, keep one open with devsy workspace ssh WORKSPACE_NAME. Ports declared in Docker Compose do not need it.
Reading CLI errors
Pass --log-output json to get errors as JSON with a stable code and a message. Some errors also include a hint and a context object.
{
"code": "UNKNOWN",
"message": "exit status 1: something failed"
}| Code | Meaning |
|---|---|
RATE_LIMITED | An upstream API rate-limited the request. Wait and retry, or authenticate. |
BUILD_FAILED_RECOVERABLE | The devcontainer build failed in a way that can be retried, for example with --recovery. |
docker_daemon_unreachable | Docker is not running or not reachable. |
canceled | The operation was canceled. |
deadline_exceeded | The operation timed out. |
unlock_required, unlock_failed | The secrets store is locked, or unlocking it failed. |
secret_backend_unavailable | The secrets backend could not be reached. |
secret_store_corrupt | The secrets store could not be read. |
secret_not_found | The requested secret does not exist. |
PANIC | Devsy hit an internal error. Please report it. |
UNKNOWN | The error was not classified. The original text is in message. |
Run with --debug to see the full error chain.
Find the right log
Devsy keeps four kinds of logs. Pick by the question you have.
| Question | Source | Command |
|---|---|---|
| What is the container or runtime printing now? | Container and runtime logs | devsy workspace logs WORKSPACE_NAME |
| What did the build and each lifecycle hook print, and how did each end? | Retained setup history | devsy workspace logs WORKSPACE_NAME --source setup |
| What state changes did the workspace go through? | Status events | devsy workspace events |
| What did a background task print? | Task logs | devsy workspace task logs |
Reading logs never reruns lifecycle commands. It never starts, unpauses, rebuilds or installs anything, and it does not need a running workspace to show history that is already stored locally.
Read setup history
List retained runs in the selected context, newest first. This works for removed workspaces too:
devsy workspace logs my-workspace --source setup --listRead the latest run, including output of hooks that succeeded:
devsy workspace logs my-workspace --source setup --result-format=plainRead one hook in one run. RUN_ID is the run UUID from --list or from the result of the command that created the run. It is not the workspace name or an op-N ID:
devsy workspace logs my-workspace --source setup --run RUN_ID \
--hook postCreateCommand --result-format=plainRead one command from a hook that runs several named or parallel commands, using its invocation ID:
devsy workspace logs my-workspace --source setup --run RUN_ID --invocation INVOCATION_IDFollow a run, including hooks that keep running after devsy workspace up returns. Ctrl-C stops only the reader:
devsy workspace logs my-workspace --source setup --run RUN_ID --followRead a run after a failed creation or CI cleanup removed the workspace. Without a workspace name you must give a run UUID:
devsy workspace logs --source setup --run RUN_ID --context CONTEXTPage through long output with --limit and --after. The default is 500 output records per page and the maximum is 2000. For --list the default is 20 runs and the maximum is 100. --after takes the opaque cursor from the previous page and must be used with the same selectors:
devsy workspace logs my-workspace --source setup --run RUN_ID --limit 200 --after CURSORUse --result-format=json for a machine-readable response. Each invocation prints one bounded JSON response. With --follow it prints one JSON response per line.
A hook that failed in the past is still a successful read, so the command exits zero and returns the hook's exit status as data. Invalid selectors and cursors, and unreadable local storage, are command errors. See Setup history for limits, redaction and when history is unavailable.
Hide live progress while keeping diagnostics
Pass --no-status to hide Devsy's live progress messages. Diagnostics still
follow --quiet, --log-level, and diagnostic format settings, and a command's
stdout and stderr remain on their original streams. Existing event and task
recording also continues when available. Hiding progress does not disable
capture or history. The flag cannot recover lifecycle output that was not
retained when the command ran. --quiet also leaves capture on, and setup
history stays readable with both flags.
VS Code-family editor launch diagnostics
For VS Code, VSCodium, and related editors, a failed CLI launch records the
flavor, operation, route, failed stage, and failure class (for example,
exit status 1 or permission denied). A successful URI-handler fallback
does not erase that CLI warning. With --debug, the logs also record executable
resolution, extension enumeration/installation, and dispatch stages. Use the
same operation value to correlate these records within the workspace task's
logs; it comes from the active IDE-launch status operation.
Executable paths, command arguments, folder URIs, editor output, and underlying
error text are deliberately omitted from these diagnostics because they may
contain private paths, host names, or credentials that cannot be reliably
redacted. Failure classes and stage names remain available; callers can inspect
the original errors programmatically. The resolved file's cli_kind identifies
an executable or batch-wrapper filename, not proof that a Windows wrapper ran.
"Launch request dispatched" means the editor CLI or OS URI handler accepted the request. It does not prove that the editor stayed running or connected over SSH. If the editor closes or does not connect, collect its own logs separately and review them for private data before sharing.
Windows: line 2: $'\r': command not found
Windows line endings break shell scripts inside the container. Add this to .gitattributes:
*.sh eol=lfNeovim: $TERM issues over SSH
See issue #1187 for a workaround.