fix: distinct error message when a CouchDB database is missing

A missing or unreachable database was reported the same way as a wrong key
(e.g. 'unknown asset_id', 'work order not found'). On not-found/failure paths
the iot, fmsr, wo and vibration servers now report that the database does not
exist in this environment and that retrying with other arguments won't help.

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>

Author: ShuxinLin

src/servers/fmsr/main.py

@@ -85,7 +85,19 @@ def _missing_asset_class_error(original: str, normalized: str) -> ErrorResult:
     return ErrorResult(error=message)
 
 
+def _is_missing_database(exc: Exception) -> bool:
+    return "Database does not exist" in str(exc)
+
+
+_MISSING_DATABASE_ERROR = (
+    f"database '{FAILURE_MODE_DBNAME}' does not exist in this environment; the "
+    "data is unavailable, do not retry with other arguments"
+)
+
+
 def _is_not_found_error(exc: Exception) -> bool:
+    if _is_missing_database(exc):
+        return False
     if isinstance(exc, (KeyError, NotFoundError)):
         return True
     response = getattr(exc, "response", None)
@@ -267,6 +279,8 @@ def _find_failure_mode_doc(asset_class: str) -> Optional[dict]:
     try:
         d = fm_db.get(f"fm:{key}", check=True)
     except Exception as exc:  # noqa: BLE001
+        if _is_missing_database(exc):
+            raise RuntimeError(_MISSING_DATABASE_ERROR) from exc
         if _is_not_found_error(exc):
             d = None
         else:
@@ -281,6 +295,8 @@ def _find_failure_mode_doc(asset_class: str) -> Optional[dict]:
                 d = docs[0]
         return d
     except Exception as exc:  # noqa: BLE001
+        if _is_missing_database(exc):
+            raise RuntimeError(_MISSING_DATABASE_ERROR) from exc
         raise RuntimeError(
             f"database lookup failed for asset_class '{key}': {exc}"
         ) from exc

src/servers/fmsr/tests/test_tools.py

@@ -293,3 +293,24 @@ async def test_mapping_tool_is_not_registered(self):
         assert "generate_failure_mode_sensor_mapping" not in {
             tool.name for tool in tools
         }
+
+
+class TestMissingDatabaseMessage:
+    @pytest.mark.anyio
+    async def test_missing_database_reports_unavailable(self, monkeypatch):
+        from couchdb3.exceptions import NotFoundError
+
+        class MissingDatabase:
+            def get(self, *args, **kwargs):
+                raise NotFoundError(
+                    '{"error":"not_found","reason":"Database does not exist."}'
+                )
+
+            find = get
+
+        monkeypatch.setattr("servers.fmsr.main.fm_db", MissingDatabase())
+
+        data = await call_tool(mcp, "get_failure_modes", {"asset_class": "pump"})
+
+        assert "does not exist in this environment" in data["error"]
+        assert "no failure_mode record" not in data["error"]

src/servers/iot/main.py

@@ -145,6 +145,19 @@ def known_sites() -> List[str]:
     return get_registry_sites() or DEFAULT_SITES
 
 
+def _missing_db_error(db: Any, name: str) -> Optional[ErrorResult]:
+    """Return an error when the database itself is absent or unreachable, so a
+    missing database is not reported as an unknown key."""
+    if db is not None and db.check():
+        return None
+    return ErrorResult(
+        error=(
+            f"database '{name}' does not exist or is unreachable in this "
+            "environment; the data is unavailable, do not retry with other arguments"
+        )
+    )
+
+
 def _is_known_site(site_name: str) -> bool:
     return site_name in known_sites()
 
@@ -224,7 +237,7 @@ def asset_ids(site_name: str) -> Union[AssetsResult, ErrorResult]:
         )
     except Exception as e:
         logger.error(f"asset_ids failed: {e}")
-        return ErrorResult(error=str(e))
+        return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(error=str(e))
 
 
 @mcp.tool(title="Get Asset Detail")
@@ -265,7 +278,9 @@ def asset_detail(site_name: str, asset_id: str) -> Union[AssetDetail, ErrorResul
         )
         docs = res.get("docs", [])
         if not docs:
-            return ErrorResult(error=f"unknown asset_id {asset_id} at site {site_name}")
+            return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(
+                error=f"unknown asset_id {asset_id} at site {site_name}"
+            )
 
         doc = docs[0]
         sensors = list(doc.get("sensors") or [])
@@ -295,7 +310,7 @@ def asset_detail(site_name: str, asset_id: str) -> Union[AssetDetail, ErrorResul
         )
     except Exception as e:
         logger.error(f"asset_detail failed: {e}")
-        return ErrorResult(error=str(e))
+        return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(error=str(e))
 
 
 @mcp.tool(title="List Measured Sensors")
@@ -322,7 +337,9 @@ def measured_sensors(
 
     sensor_list = get_sensor_list(asset_id)
     if not sensor_list:
-        return ErrorResult(error=f"unknown asset_id {asset_id} or no sensors found")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error=f"unknown asset_id {asset_id} or no sensors found"
+        )
 
     return SensorsResult(
         site_name=site_name,
@@ -366,7 +383,9 @@ def installed_sensors(
         )
         docs = res.get("docs", [])
         if not docs:
-            return ErrorResult(error=f"unknown asset_id {asset_id} at site {site_name}")
+            return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(
+                error=f"unknown asset_id {asset_id} at site {site_name}"
+            )
         names = list(docs[0].get("sensors") or [])
         return SensorsResult(
             site_name=site_name,
@@ -377,7 +396,7 @@ def installed_sensors(
         )
     except Exception as e:
         logger.error(f"installed_sensors failed: {e}")
-        return ErrorResult(error=str(e))
+        return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(error=str(e))
 
 
 @mcp.tool(title="List Assets")
@@ -435,7 +454,7 @@ def assets(
         )
     except Exception as e:
         logger.error(f"assets failed: {e}")
-        return ErrorResult(error=str(e))
+        return _missing_db_error(asset_db, ASSET_DBNAME) or ErrorResult(error=str(e))
 
 
 @mcp.tool(title="Find Assets By Sensors")
@@ -606,7 +625,7 @@ def stream_extent(
             total_records += 1
 
         if total_records == 0:
-            return ErrorResult(
+            return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
                 error=f"no records for asset_id {asset_id}"
                 + (f", sensor {sensor}" if sensor else "")
             )
@@ -638,7 +657,9 @@ def stream_extent(
         return ErrorResult(error=str(e))
     except Exception as e:
         logger.error(f"stream_extent failed: {e}")
-        return ErrorResult(error="unable to inspect telemetry stream extent")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error="unable to inspect telemetry stream extent"
+        )
 
 
 @mcp.tool(title="Get Sensor History")
@@ -704,7 +725,9 @@ def history(
             )
         available_sensors = get_sensor_list(asset_id)
         if not available_sensors:
-            return ErrorResult(error=f"unknown asset_id {asset_id} or no sensors found")
+            return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error=f"unknown asset_id {asset_id} or no sensors found"
+        )
         unknown = [
             sensor for sensor in selected_sensors if sensor not in available_sensors
         ]
@@ -763,7 +786,9 @@ def history(
         return ErrorResult(error=str(e))
     except Exception as e:
         logger.error(f"history failed: {e}")
-        return ErrorResult(error="unable to retrieve telemetry history")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error="unable to retrieve telemetry history"
+        )
 
     next_cursor = None
     if has_more:
@@ -828,7 +853,9 @@ def latest_reading(
     if sensor is not None:
         available_sensors = get_sensor_list(asset_id)
         if not available_sensors:
-            return ErrorResult(error=f"unknown asset_id {asset_id} or no sensors found")
+            return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error=f"unknown asset_id {asset_id} or no sensors found"
+        )
         if sensor not in available_sensors:
             return ErrorResult(error=f"unknown sensor {sensor} for asset_id {asset_id}")
 
@@ -856,10 +883,12 @@ def latest_reading(
         return ErrorResult(error=str(e))
     except Exception as e:
         logger.error(f"latest_reading failed: {e}")
-        return ErrorResult(error="unable to retrieve latest telemetry reading")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error="unable to retrieve latest telemetry reading"
+        )
 
     if latest_doc is None or latest_timestamp is None or latest_datetime is None:
-        return ErrorResult(
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
             error=f"no records for asset_id {asset_id}"
             + (f", sensor {sensor}" if sensor else "")
         )
@@ -930,10 +959,14 @@ def sensor_coverage(
         return ErrorResult(error=str(e))
     except Exception as e:
         logger.error(f"sensor_coverage failed: {e}")
-        return ErrorResult(error="unable to calculate sensor coverage")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error="unable to calculate sensor coverage"
+        )
 
     if docs_scanned == 0:
-        return ErrorResult(error=f"unknown asset_id {asset_id} or no records found")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error=f"unknown asset_id {asset_id} or no records found"
+        )
 
     sensors = [coverage[field].result(field) for field in sorted(coverage)]
     message = (
@@ -996,7 +1029,9 @@ def sensor_stats(
 
     available_sensors = get_sensor_list(asset_id)
     if not available_sensors:
-        return ErrorResult(error=f"unknown asset_id {asset_id} or no sensors found")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error=f"unknown asset_id {asset_id} or no sensors found"
+        )
     if sensor is not None and sensor not in available_sensors:
         return ErrorResult(error=f"unknown sensor {sensor} for asset_id {asset_id}")
 
@@ -1035,10 +1070,12 @@ def sensor_stats(
         return ErrorResult(error=str(e))
     except Exception as e:
         logger.error(f"sensor_stats failed: {e}")
-        return ErrorResult(error="unable to calculate sensor statistics")
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
+            error="unable to calculate sensor statistics"
+        )
 
     if records_in_window == 0:
-        return ErrorResult(
+        return _missing_db_error(iot_db, IOT_DBNAME) or ErrorResult(
             error=f"no records for asset_id {asset_id}"
             + (f", sensor {sensor}" if sensor else "")
         )

src/servers/iot/tests/test_tools.py

@@ -1795,3 +1795,32 @@ async def test_discovery_integration(self):
         assert "assets" in data
         assert any(asset["asset_id"] == "Chiller 6" for asset in data["assets"])
         assert data["total_assets"] > 0
+
+
+class TestMissingDatabaseMessage:
+    @pytest.mark.anyio
+    async def test_wrong_asset_id_reports_unknown_key(self, mock_asset_db, mock_iot_db):
+        mock_asset_db.find.return_value = {"docs": [{"siteid": "MAIN"}]}
+        mock_iot_db.find.return_value = {"docs": []}
+        mock_iot_db.check.return_value = True
+
+        data = await call_tool(
+            mcp, "measured_sensors", {"site_name": "MAIN", "asset_id": "Pump-X"}
+        )
+
+        assert data["error"] == "unknown asset_id Pump-X or no sensors found"
+
+    @pytest.mark.anyio
+    async def test_missing_database_reports_unavailable(
+        self, mock_asset_db, mock_iot_db
+    ):
+        mock_asset_db.find.return_value = {"docs": [{"siteid": "MAIN"}]}
+        mock_iot_db.find.side_effect = RuntimeError("Database does not exist.")
+        mock_iot_db.check.return_value = False
+
+        data = await call_tool(
+            mcp, "measured_sensors", {"site_name": "MAIN", "asset_id": "Chiller 6"}
+        )
+
+        assert "does not exist or is unreachable" in data["error"]
+        assert "do not retry" in data["error"]

src/servers/vibration/couchdb_client.py

@@ -47,6 +47,12 @@ def _get_db() -> Optional[couchdb3.Database]:
         return None
 
 
+def database_available() -> bool:
+    """True when the vibration database exists and CouchDB is reachable."""
+    db = _get_db()
+    return bool(db and db.check())
+
+
 def fetch_vibration_timeseries(
     asset_id: str,
     sensor_name: str,

src/servers/vibration/main.py

@@ -19,7 +19,12 @@
 from mcp.server.fastmcp import FastMCP
 from pydantic import BaseModel
 
-from .couchdb_client import fetch_vibration_timeseries, list_sensor_fields
+from .couchdb_client import (
+    VIBRATION_DBNAME,
+    database_available,
+    fetch_vibration_timeseries,
+    list_sensor_fields,
+)
 from .data_store import store
 from .dsp.bearing_freqs import (
     COMMON_BEARINGS,
@@ -58,6 +63,20 @@ class ErrorResult(BaseModel):
     error: str
 
 
+def _missing_db_error() -> Optional[ErrorResult]:
+    """Return an error when the database itself is absent or unreachable, so a
+    missing database is not reported as missing asset/sensor data."""
+    if database_available():
+        return None
+    return ErrorResult(
+        error=(
+            f"database '{VIBRATION_DBNAME}' does not exist or is unreachable in "
+            "this environment; the data is unavailable, do not retry with other "
+            "arguments"
+        )
+    )
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -155,7 +174,7 @@ def get_vibration_data(
     """
     result = fetch_vibration_timeseries(asset_id, sensor_name, start, final)
     if result is None:
-        return ErrorResult(
+        return _missing_db_error() or ErrorResult(
             error=f"No vibration data found for asset '{asset_id}', "
             f"sensor '{sensor_name}' in time range starting {start}."
         )
@@ -190,7 +209,7 @@ def list_vibration_sensors(
     """
     sensors = list_sensor_fields(asset_id)
     if not sensors:
-        return ErrorResult(
+        return _missing_db_error() or ErrorResult(
             error=f"No sensors found for asset '{asset_id}' at site '{site_name}'."
         )
     return {

src/servers/vibration/tests/test_missing_database.py

@@ -0,0 +1,29 @@
+"""A wrong asset and a missing database produce different error messages."""
+
+import pytest
+
+from servers.vibration.main import mcp
+
+from .conftest import call_tool
+
+_ARGS = {"site_name": "MAIN", "asset_id": "Motor-X"}
+
+
+@pytest.mark.anyio
+async def test_wrong_asset_reports_no_sensors(mock_db):
+    mock_db.return_value.find.return_value = {"docs": []}
+    mock_db.return_value.check.return_value = True
+
+    data = await call_tool(mcp, "list_vibration_sensors", _ARGS)
+
+    assert data["error"] == "No sensors found for asset 'Motor-X' at site 'MAIN'."
+
+
+@pytest.mark.anyio
+async def test_missing_database_reports_unavailable(mock_db):
+    mock_db.return_value.find.side_effect = RuntimeError("Database does not exist.")
+    mock_db.return_value.check.return_value = False
+
+    data = await call_tool(mcp, "list_vibration_sensors", _ARGS)
+
+    assert "does not exist or is unreachable" in data["error"]