Issue with Workspace URL from Theia Cloud Launch — 503 on Initial Load

[Subham7201]

Hi team,

We’re currently using the @eclipse-theiacloud/common package to programmatically launch workspaces and retrieve their URLs. Our setup looks like this:

import { LaunchRequest, TheiaCloud, RequestOptions } from '@eclipse-theiacloud/common';

export async function LaunchAndRedirect(request: wsLaunchRequest) {
  const launchRequest: LaunchRequest = request.request;
  const options: RequestOptions = request.options;

  const url = await TheiaCloud.launch(launchRequest, options);
  return url;
}

export type wsLaunchRequest = {
  request: LaunchRequest;
  options: RequestOptions;
};

This function is triggered on a "Load" button click.

The issue we’re facing is that while TheiaCloud.launch() successfully returns a URL, navigating to it immediately results in a 503 Service Unavailable error. The workspace becomes accessible only after manually refreshing the browser a few times.

What we’ve tried:

• Initially, we relied on the returned URL from launch() and redirected right away.

• To handle the 503 issue, we added a fetch() call in our code to check if the URL returns an HTTP 200 before proceeding. It does return 200 — even while the browser still shows 503.

This indicates that the endpoint might be technically "up" but not fully ready for browser-based interaction — possibly the IDE is not yet initialized or fully responsive.

The question:

• Is there a readiness check mechanism provided by Theia Cloud to determine when a workspace is actually ready for browser use beyond just the HTTP 200 status?

• If not, what would be the recommended approach to handle this delay more reliably and ensure users don’t hit a 503 or have to refresh repeatedly?

Any insights, documentation pointers, or recommended patterns would be greatly appreciated.

Thanks in advance!

[jfaltermeier]

Hm, I haven't seen this before.
Usually we only set the URL if we receive a 200 status code from this URL.
If we get a status code other than 404 or 503, we eventually return the URL as well, assuming that it is likely not a Theia Cloud issue:

theia-cloud/java/operator/org.eclipse.theia.cloud.operator/src/main/java/org/eclipse/theia/cloud/operator/handler/AddedHandlerUtil.java

Line 186 in 55813e2

} else if (code != 404 && code != 503 && !updateURL) {

So getting a 503 is a bit strange, but as you mentioned, you're getting a 200 with fetch, and a 503 in the browser, so it might be the same cause.

In our usual demo application, we start Theia like this:
https://github.com/eclipse-theia/theia-ide/blob/073927e8ca91a19f65bfd0b71a47f73b04b685a1/browser.Dockerfile#L68

In Theia Cloud, we do not know too much about the application being started, so we rely on HTTP status codes as a simple readiness check.

One thing you could try is adding a Docker HEALTHCHECK:
https://docs.docker.com/reference/dockerfile/#healthcheck

As far as I can see, the Theia Node application exposes a /ready endpoint, e.g. with the Try Now Demo at:
https://ws.theia-cloud.io/session-id/ready
You could try using this in your application Dockerfile as a HEALTHCHECK.