Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 12. Troubleshoot OpenShift Dev Spaces

Diagnose and resolve common OpenShift Dev Spaces workspace issues by collecting logs and applying targeted fixes.

When a workspace fails to start, runs slowly, or displays unexpected errors, start by reviewing logs from the workspace pod, the OpenShift Dev Spaces operator, and the language server.

12.1. OpenShift Dev Spaces workspace logs
Copy link

OpenShift Dev Spaces workspace logs capture IDE extension activity, container memory events, and process errors. Review these logs to diagnose workspace failures, debug misbehaving extensions, and identify memory issues.

An IDE extension misbehaves or needs debugging
The logs list the plugins that have been loaded by the editor.
The container runs out of memory
The logs contain an OOMKilled error message. Processes running in the container attempted to request more memory than is configured to be available to the container.
A process runs out of memory
The logs contain an error message such as OutOfMemoryException. A process inside the container ran out of memory without the container noticing.

12.1.1. View workspace logs in CLI
Copy link

Use the OpenShift command-line interface (CLI) to observe OpenShift Dev Spaces workspace logs to troubleshoot startup failures and runtime errors.

Prerequisites

  • You have the OpenShift Dev Spaces workspace <workspace_name> running.
  • You have an OpenShift CLI session with access to the OpenShift project <namespace_name> containing this workspace.

Procedure

  1. Get the logs from the pod running the <workspace_name> workspace in the <namespace_name> project: 

    $ oc logs --follow --namespace='<workspace_namespace>' \
  --selector='controller.devfile.io/devworkspace_name=<workspace_name>'

12.1.2. View workspace logs in OpenShift console
Copy link

Use the OpenShift console to observe OpenShift Dev Spaces workspace logs.

Prerequisites

  • You have a running OpenShift Dev Spaces workspace.
  • You have access to the OpenShift web console.

Procedure

  1. In the OpenShift Dev Spaces dashboard, go to Workspaces.
  2. Click a workspace name to display the workspace overview page. This page displays the OpenShift project name <project_name>.
  3. Click the upper right Applications menu, and click the OpenShift console link.
  4. Run the next steps in the OpenShift console, in the Administrator perspective.
  5. Click Workloads > Pods to see a list of all the active workspaces.
  6. In the Project drop-down menu, select the <project_name> project to narrow the search.
  7. Click the name of the running pod that runs the workspace. The Details tab contains the list of all containers with additional information.
  8. Go to the Logs tab.

In the Microsoft Visual Studio Code - Open Source editor running in your workspace, configure the installed language server and debug adapter extensions to view their logs.

Prerequisites

  • You have a running OpenShift Dev Spaces workspace with Microsoft Visual Studio Code - Open Source as the editor.
  • You have a language server or debug adapter extension installed in the editor.

Procedure

  1. Configure the extension: click File > Preferences > Settings, expand the Extensions section, search for your extension, and set the trace.server or similar configuration to verbose, if such configuration exists. Refer to the extension documentation for further configuration.
  2. View your language server logs by clicking View > Output, and selecting your language server in the drop-down list for the Output view.

12.2. Slow workspace troubleshooting
Copy link

Identify configuration changes that reduce OpenShift Dev Spaces workspace startup time and improve runtime performance, including image pre-pulling, storage strategy tuning, and resource adjustments.

12.2.1. Improving workspace start time
Copy link

Caching images with Image Puller

Role: Administrator

When starting a workspace, OpenShift pulls the images from the registry. A workspace can include many containers meaning that OpenShift pulls Pod’s images (one per container). Depending on the size of the image and the bandwidth, it can take a long time.

Image Puller is a tool that can cache images on each of OpenShift nodes. As such, pre-pulling images can improve start times.

Choosing better storage type

Role: Administrator and user

Every workspace has a shared volume attached. This volume stores the project files, so that when restarting a workspace, changes are still available. Depending on the storage, attach time can take up to a few minutes, and I/O can be slow.

Installing offline

Role: Administrator

Components of OpenShift Dev Spaces are OCI images. Configure Red Hat OpenShift Dev Spaces in offline mode to reduce any extra download at runtime because everything needs to be available from the beginning.

Reducing the number of public endpoints

Role: Administrator

For each endpoint, OpenShift is creating OpenShift Route objects. Depending on the underlying configuration, this creation can be slow.

To avoid this problem, reduce the exposure. For example, Microsoft Visual Code - Open Source has three optional routes. These routes automatically detect a new port listening inside containers and redirect traffic for processes using a local IP address (127.0.0.1).

By reducing the number of endpoints and checking endpoints of all plugins, workspace start can be faster.

12.2.2. Improving workspace runtime performance
Copy link

Providing enough CPU resources

Plugins consume CPU resources. For example, when a plugin provides IntelliSense features, adding more CPU resources can improve performance.

Ensure the CPU settings in the devfile definition, devfile.yaml, are correct: 

components:
  - name: tools
    container:
      image: quay.io/devfile/universal-developer-image:ubi8-latest
      cpuLimit: 4000m
      cpuRequest: 1000m
cpuLimit
Specifies the CPU limit.
cpuRequest
Specifies the CPU request.
Providing enough memory

Plug-ins consume CPU and memory resources. For example, when a plugin provides IntelliSense features, collecting data can consume all the memory allocated to the container.

Providing more memory to the container can increase performance. Ensure that memory settings in the devfile definition devfile.yaml file are correct. 

components:
  - name: tools
    container:
      image: quay.io/devfile/universal-developer-image:ubi8-latest
      memoryLimit: 6G
      memoryRequest: 512Mi
memoryLimit
Specifies the memory limit.
memoryRequest
Specifies the memory request.

12.3. Troubleshoot network problems
Copy link

Diagnose and resolve OpenShift Dev Spaces network connectivity issues including WebSocket failures, proxy configuration problems, and Domain Name System (DNS) resolution errors.

Prerequisites

  • You have an active workspace URL or the OpenShift Dev Spaces dashboard URL.

Procedure

  1. Verify that the browser supports WebSocket connections by opening the browser developer tools (F12), navigating to the Console tab, and running: 

    var ws = new WebSocket('wss://echo.websocket.org');
ws.onopen = function() { console.log('WebSocket OK'); ws.close(); };
ws.onerror = function() { console.log('WebSocket FAILED'); };

    If the output is WebSocket FAILED, WebSocket connections are blocked. Contact your network administrator to allow WSS connections on port 443.

  2. Verify that firewall rules allow WebSocket Secure (WSS) connections on port 443 to the OpenShift Dev Spaces hostname.
  3. If your network uses a proxy server, verify that the proxy allows WebSocket upgrade requests. Some proxies block HTTP upgrade headers by default.

  4. Verify DNS resolution from a workspace terminal: 

    nslookup <devspaces_hostname>

    If the DNS lookup fails, the workspace Pod cannot resolve the OpenShift Dev Spaces hostname. Verify the cluster DNS configuration and any custom DNS settings in the workspace namespace.

  5. If you encounter x509: certificate signed by unknown authority errors when connecting to an HTTPS endpoint from inside a workspace, the workspace does not trust the TLS certificate.

    Contact your administrator to import the required Certificate Authority (CA) certificates.

Verification

  • Open a workspace and verify that the IDE loads without connection errors.
  • Verify that Git operations (clone, push, pull) complete without network timeouts.

12.4. Webview loading error troubleshooting
Copy link

If you use Microsoft Visual Studio Code - Open Source in a private browsing window, you might encounter an error message. The error is: Error loading webview: Error: Could not register service workers.

This is a known issue affecting the following browsers:

  • Google Chrome in Incognito mode
  • Mozilla Firefox in Private Browsing mode
Expand
Table 12.1. Dealing with the webview error in a private browsing window
BrowserWorkarounds

Google Chrome

Go to Settings Privacy and security Cookies and other site data Allow all cookies.

Mozilla Firefox

Webviews are not supported in Private Browsing mode. See the Mozilla bug report for details.

12.5. Troubleshooting devfile issues
Copy link

Diagnose and resolve common devfile issues that prevent workspaces from starting or operating correctly. Issues include syntax errors, component failures, lifecycle command problems, and volume or endpoint misconfigurations.

12.5.1. Devfile syntax and validation errors
Copy link

Expand
Table 12.2. Devfile syntax and validation error symptoms and resolutions
SymptomResolution

Workspace fails to start with Failed to process devfile or invalid devfile.

The devfile contains a syntax error. Validate the devfile YAML against the devfile schema. Check for incorrect indentation, missing required fields, or unsupported properties.

Workspace starts but ignores devfile changes.

OpenShift Dev Spaces caches devfile content. Delete the workspace and create a new one from the updated repository URL to apply devfile changes.

Error: schemaVersion is required.

The devfile is missing the schemaVersion field. Add schemaVersion: 2.2.2 as the first line in the devfile.

12.5.2. Component and container errors
Copy link

Expand
Table 12.3. Component and container error symptoms and resolutions
SymptomResolution

Workspace Pod shows CrashLoopBackOff for a devfile component.

The container image specified in the devfile component fails to start. Verify that the image exists and runs correctly outside of OpenShift Dev Spaces. Check container logs for details.

openssl or libbrotli not found error in workspace startup.

The container image is missing libraries required by VS Code. Add RUN yum install compat-openssl11 libbrotli to the Dockerfile for the image.

Devfile component does not have enough memory and is OOMKilled.

The default memory limit is insufficient for the workload. Add or increase memoryLimit in the devfile component.

12.5.3. Command and lifecycle errors
Copy link

Expand
Table 12.4. Command and lifecycle error symptoms and resolutions
SymptomResolution

A postStart command fails silently.

The command exits with a non-zero code. Check workspace logs for the command output. Verify the command path and syntax. Ensure the command is executable inside the container.

Multiple postStart commands do not all run.

The devfile specification allows only one postStart event. Combine multiple initialization commands into a single shell script and reference that script as the postStart command.

12.5.4. Volume and endpoint errors
Copy link

Expand
Table 12.5. Volume and endpoint error symptoms and resolutions
SymptomResolution

Source code changes are lost after workspace restart.

The /projects volume is not persistent. Verify that the workspace is not using ephemeral storage. Check the pvcStrategy in the CheCluster Custom Resource.

Endpoint URL returns 502 Bad Gateway or 503 Service Unavailable.

The application inside the workspace is not listening on the port declared in the devfile endpoint. Verify the targetPort value matches the port your application binds to.

Endpoint is not accessible from outside the workspace.

By default, endpoints use public exposure. Verify the exposure field in the devfile endpoint definition. If set to internal, the endpoint is only accessible within the workspace Pod.

Revised on 2026-06-15 09:58:13 UTC

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top