Devsy
Troubleshooting

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"
}
CodeMeaning
RATE_LIMITEDAn upstream API rate-limited the request. Wait and retry, or authenticate.
BUILD_FAILED_RECOVERABLEThe devcontainer build failed in a way that can be retried, for example with --recovery.
docker_daemon_unreachableDocker is not running or not reachable.
canceledThe operation was canceled.
deadline_exceededThe operation timed out.
unlock_required, unlock_failedThe secrets store is locked, or unlocking it failed.
secret_backend_unavailableThe secrets backend could not be reached.
secret_store_corruptThe secrets store could not be read.
secret_not_foundThe requested secret does not exist.
PANICDevsy hit an internal error. Report it.
UNKNOWNThe 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.

QuestionSourceCommand
What is the container or runtime printing now?Container and runtime logsdevsy workspace logs WORKSPACE_NAME
What did the build and each lifecycle hook print, and how did each end?Retained setup historydevsy workspace logs WORKSPACE_NAME --source setup
What state changes did the workspace go through?Status eventsdevsy workspace events
What did a background task print?Task logsdevsy 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 --list

Read the latest run, including output of hooks that succeeded:

devsy workspace logs my-workspace --source setup --result-format=plain

Read 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=plain

Read 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_ID

Follow 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 --follow

Read 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 CONTEXT

Page 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 CURSOR

Use --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=lf

Neovim: $TERM issues over SSH

See issue #1187 for a workaround.

On this page