Debug a failing workspace

Debug a failing workspace by starting it in debug mode. Debug mode keeps containers running after postStart command failures, giving you time to inspect logs and diagnose the issue.

When debug mode is enabled:

  • If a postStart lifecycle command fails, the container sleeps instead of terminating, giving you time to connect and inspect the failure.

  • Logs from postStart commands are written to /tmp/poststart-stdout.txt and /tmp/poststart-stderr.txt inside the workspace container.

  • The workspace deployment remains available for the duration of the configured progressTimeout (default: 5 minutes) before scaling down.

Prerequisites

  • You have a running Che instance.

  • You have access to the Che dashboard.

Procedure

Start a stopped workspace in debug mode:

  1. In the Che dashboard, go to the Workspaces page.

  2. Click the kebab menu (⋮) for the workspace you want to debug.

  3. Select Open in Debug mode.

    The workspace starts with the controller.devfile.io/debug-start annotation set to true, and the Logs tab opens.

Restart a running workspace in debug mode:

  1. In the Che dashboard, go to the Workspaces page.

  2. Click the kebab menu (⋮) for the running workspace.

  3. Select Restart in Debug mode.

    The workspace restarts with debug mode enabled, and the Logs tab opens.

Inspect a failing workspace:

  1. Wait for the workspace to report a failure in the Logs tab. Look for error messages or status conditions indicating startup problems. If no failure occurs within the progressTimeout period (default: 5 minutes), the workspace will scale down automatically.

  2. Use kubectl to exec into the workspace container:

    $ kubectl exec --namespace='<workspace_namespace>' \
  deploy/workspace<workspace_id> -- /bin/bash

  3. Review the postStart command logs:

    $ cat /tmp/poststart-stderr.txt
$ cat /tmp/poststart-stdout.txt
Verification

  • In the Logs tab, verify that the workspace status conditions include the message DevWorkspace is starting in debug mode.

  • If a postStart command fails, verify that the container remains running and that /tmp/poststart-stderr.txt contains the failure details.

The controller.devfile.io/debug-start annotation is managed by the Che dashboard. Manually patching this annotation on a DevWorkspace resource using kubectl will not persist, because the dashboard reconciles the annotation on every start or restart operation.

Always use the dashboard actions described above to enable debug mode.
Additional resources