Troubleshooting
Known issues and workarounds. For Linux 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. 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 one 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 or starts, unpauses, rebuilds or installs anything. Stored history shows without a running workspace.
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 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. With --list, the default is 20 runs and the maximum is 100. --after takes the cursor from the previous page, with the same selectors:
devsy workspace logs my-workspace --source setup --run RUN_ID --limit 200 --after CURSORUse --result-format=json for machine-readable output. Each invocation prints one JSON response, and with --follow one response per line.
A failed hook is still a successful read. The command exits zero and returns the hook's exit status in the output. Invalid selectors, invalid 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 live progress messages. Diagnostics still follow --quiet, --log-level and the diagnostic format settings. A command's stdout and stderr stay on their original streams, and event and task recording continue. The flag does not turn off capture or history. --quiet also leaves capture on, and setup history stays readable with both flags.
VS Code editor launch diagnostics
For VS Code, VSCodium and related editors, a failed CLI launch records the flavor, operation, route, failed stage and failure class, such as 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 and installation, and dispatch stages. Use the operation value to match records in the workspace task's logs.
Diagnostics omit executable paths, command arguments, folder URIs, editor output and error text, because these can contain private paths, host names or credentials. Failure classes and stage names remain. The cli_kind value names an executable or batch wrapper. It does not show that a Windows wrapper ran.
A dispatched launch request means the editor CLI or OS URI handler accepted it. Devsy does not track whether the editor stayed running or connected over SSH. If the editor closes or does not connect, collect its own logs and check them for private data before you share them.
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.