Devsy
Troubleshooting

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"
}
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. Please 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 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. 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 --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 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=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. 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 CURSOR

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

Neovim: $TERM issues over SSH

See issue #1187 for a workaround.

On this page