Return a clear 503 response when Smart Search cannot reach any ML server

[ilya-yarets]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

Platform

• Server
• Web
• Mobile

Problem

When all configured machine-learning URLs are unavailable, a text Smart Search request returns a generic internal-server error:

POST /api/search/smart
HTTP/1.1 500 Internal Server Error

{"message":"Failed to search smart"}

The server log contains the actual cause:

WARN  Machine learning request to "<redacted-remote-ml-url>" failed: fetch failed
ERROR Machine learning request ... failed for all URLs

This was reproduced on Immich v3.1.0 with a single remote ML URL configured through the admin UI and the remote worker intentionally offline. The local database and Immich containers were healthy.

The current MachineLearningRepository.predict implementation tries all configured URLs and then throws a regular Error. ErrorInterceptor treats it as an unknown error and replaces it with the route-level generic 500 message. The web error handler already displays a server-provided message, so a more specific API response should also give the user an actionable toast.

Relevant code:

• https://github.com/immich-app/immich/blob/main/server/src/repositories/machine-learning.repository.ts
• https://github.com/immich-app/immich/blob/main/server/src/middleware/error.interceptor.ts
• https://github.com/immich-app/immich/blob/main/web/src/lib/utils/handle-error.ts

Reproduction

1. Configure one remote Machine Learning URL in Administration > Settings > Machine Learning.
2. Make that ML worker unreachable.
3. Run a text Smart Search query.
4. Observe HTTP 500 with {"message":"Failed to search smart"} even though the failure is a temporary dependency outage.

Suggested behavior

Return a dependency-specific response when every configured ML endpoint has failed, for example:

HTTP/1.1 503 Service Unavailable

{"message":"Machine learning service is unavailable"}

A narrowly scoped implementation could:

• throw a typed error after MachineLearningRepository exhausts all configured URLs;
• map only that typed error to ServiceUnavailableException at the Smart Search HTTP boundary;
• retain detailed per-endpoint failures in server logs without exposing configured URLs to clients;
• add a regression test for the 503 response and message.

This request does not propose automatic fallback, queue changes, or exposing endpoint details. It only makes the temporary ML dependency failure distinguishable from an unexpected server bug.

Related issue #28289 discusses background queue behavior with an offline ML worker; this request is limited to the synchronous Smart Search API response and user-facing error.

[github-actions[bot]]

This discussion has automatically been closed as it is likely a duplicate. We get a lot of duplicate threads each day, which is why we ask you in the template to confirm that you searched for duplicates before opening one. If you're sure this is not a duplicate, please leave a comment and we will reopen the thread if necessary.

[ilya-yarets]

The discussion was created through the API, which unintentionally omitted the required duplicate-search checkbox from the feature-request form. I have now added the checkbox and platform fields.

I searched open and closed feature requests and issues before posting. The closest matches I found were #28289, which concerns background queue behavior with an offline ML worker, and #16215, which concerns reporting failed background jobs. Neither covers the synchronous Smart Search API returning a generic HTTP 500 when every configured ML endpoint is unavailable.

Please reopen this discussion if it is not considered a duplicate. If there is an existing request that covers this exact API and user-facing error behavior, a link would be appreciated.

[ilya-yarets]

Following up after the v3.2.x releases: is this expected to be fixed now, or is it still open? I checked v3.2.2 and MachineLearningRepository.predict still appears to throw a regular Error (failed for all URLs), so I believe synchronous Smart Search will still surface the generic HTTP 500 when all configured ML URLs are unavailable. If a different change or linked issue/PR addresses this, could you please point me to it?

[bo0tzz]

This thread is still open, what makes you think it'd be expected to be fixed?