HTTP 524 (gateway timeout) from ClearlyDefined aborts run with exit 127

[MatthewKhouzam]

Summary

dash-licenses intermittently fails hard when ClearlyDefined returns an HTTP 524 (upstream/gateway timeout). Unlike a transient rate-limit response, the 524 aborts the run: the tool reports an internal error and exits with code 127, failing the whole CI job.

Observed behavior

While querying ClearlyDefined for license data, we get:

[main] INFO Querying ClearlyDefined for license data for 50 items.
[main] INFO Querying ClearlyDefined for license data for 50 items.
[main] ERROR Error response from ClearlyDefined 524
ERROR: Command [
  ".../node_modules/@eclipse-dash/nodejs-wrapper/download/dash-licenses.jar",
  "-timeout",
  ".../license-check-summary.txt",
] exit code (127) means dash-licenses has encountered an internal error
ERROR: Detected an internal error in dash-licenses - run inconclusive
error Command failed with exit code 127.

HTTP 524 is a Cloudflare-specific status meaning the origin server did not respond within the gateway timeout, i.e. ClearlyDefined took too long to answer the batch query rather than actively refusing/throttling it.

Impact

• A single 524 response terminates the entire license check as an "internal error" (exit 127), even though the failure is upstream and transient.
• Retrying at the workflow level does not reliably help: the queries are slow and each attempt can hit the timeout again, eventually exceeding the job's max execution time.

Real-world example from a downstream project (Trace Viewer for VSCode), where the 3PP License Check job kept hitting 524 across retries until it exceeded the 20-minute job limit:

https://github.com/eclipse-cdt-cloud/vscode-trace-extension/actions/runs/34277342618/job/102233502459

Suggestions

1. Treat an HTTP 524 (and other 5xx gateway responses) from ClearlyDefined as a retriable / transient backend error rather than an internal error that aborts with exit 127. This aligns with #145 (make ClearlyDefined API call error handling more resilient) and #243 (option to not fail the build on a backend issue).
2. Consider automatic in-tool retry with backoff for 5xx responses, and/or reducing the ClearlyDefined batch size on timeout (related to #128).
3. Distinguish "backend unavailable / inconclusive" from a genuine license-check failure so downstream workflows can choose to treat it as a warning.

Related

• #448 (Frequent 429 errors from ClearlyDefined) — related but distinct: that is throttling (429), this is a gateway timeout (524).
• #145 — Make ClearlyDefined API call error handling more resilient
• #243 — Option to not fail the build if there is a backend issue
• #128 — ClearlyDefined data search time out; maybe decrease batch size

Note: this is a real problem, but I used claude sonnet 4.5 to format the document.