fix(remote): unify unsupported operation errors and warnings (#4414)

Remote SDKs report Cloud-specific errors against self-hosted servers,
and some Python wrappers raise different exception types for the same
unsupported operation. The sync index wrapper also warns that `replace`
is ignored even though Rust forwards it to the server.

Use backend-neutral table/server diagnostics and the existing
`NotSupported` error conversions for unsupported manifest operations,
blob ranges, primary keys, optimization, and HNSW-PQ indexes. Sync
Python delegates to the async paths, so manifest operations and
`optimize()` consistently raise `NotImplementedError`. Legacy and
config-based HNSW-PQ creation share the same error and alternative-index
advice.

Remove the false replacement warning and simplify the ignored
GPU-accelerator warning. Keep the deprecated cleanup/compaction no-ops,
with backend-neutral warnings that do not assume automatic server
maintenance.

Embedding configuration forwarding and stale warning removal are now
supplied by #4408 in `main`. Retain the regression that verifies full
embedding metadata and warning-free remote creation alongside the
diagnostics tests.

Validation against the merged `main` revision `bbc4aebe` and Lance
14.0.0-beta.1:

- Rebuilt the Python extension with `uv run --extra tests --extra dev
maturin develop --extras tests,dev`; all 122 remote Python tests passed.
Root Ruff checks and formatting passed using the uv-managed environment.
- `pnpm build`, `pnpm lint`, formatting, and `pnpm run docs` passed; all
47 remote Node tests and the focused local vector-index regression
passed.
- All 583 Rust remote tests and 54 query unit tests passed, along with
`cargo check --quiet --features remote --tests --examples`, `cargo
clippy --quiet --features remote --tests --examples`, and `cargo fmt
--all`.

Fixes #4393

<!-- lance-gatekeeper-fix:v1 agent=10bafd337999f4910855c3a9b71e7dcf
generation=1 -->

---------

Co-authored-by: Gatefixer <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>

nodejs/__test__/remote.test.ts

@@ -28,6 +28,7 @@ import {
   StaticHeaderProvider,
 } from "../lancedb/header";
 import { Index } from "../lancedb/indices";
+import { LocalTable } from "../lancedb/table";
 
 // Test-only header providers
 class CustomProvider extends HeaderProvider {
@@ -93,6 +94,58 @@ async function withMockDatabase(
 }
 
 describe("remote connection", () => {
+  it("reports unsupported operations with backend-neutral errors", async () => {
+    await withMockDatabase(
+      (req, res) => {
+        expect(req.url).toBe("/v1/table/test/describe/");
+        res.writeHead(200, { "Content-Type": "application/json" }).end(
+          JSON.stringify({
+            version: 1,
+            schema: {
+              fields: [
+                { name: "id", type: { type: "int64" }, nullable: false },
+                {
+                  name: "vector",
+                  type: {
+                    type: "fixed_size_list",
+                    fields: [
+                      { name: "item", type: { type: "float" }, nullable: true },
+                    ],
+                    length: 2,
+                  },
+                  nullable: false,
+                },
+              ],
+            },
+          }),
+        );
+      },
+      async (db) => {
+        const table = (await db.openTable("test")) as LocalTable;
+        const cases: [() => Promise<unknown>, string][] = [
+          [() => table.usesV2ManifestPaths(), "uses_v2_manifest_paths"],
+          [() => table.migrateManifestPathsV2(), "migrate_manifest_paths_v2"],
+          [
+            () => table.setUnenforcedPrimaryKey("id"),
+            "set_unenforced_primary_key",
+          ],
+          [() => table.optimize(), "optimize"],
+          [
+            () => table.createIndex("vector", { config: Index.hnswPq() }),
+            "IVF_HNSW_PQ",
+          ],
+        ];
+        for (const [run, operation] of cases) {
+          let message = `LanceDBError: not supported: ${operation} is not supported for remote tables.`;
+          if (operation === "IVF_HNSW_PQ") {
+            message += " Please use IVF_HNSW_SQ instead.";
+          }
+          await expect(run()).rejects.toThrow(new Error(message));
+        }
+      },
+    );
+  });
+
   it("rejects nprobes(0) before sending a query", async () => {
     const requests: string[] = [];
     await withMockDatabase(

nodejs/src/table.rs

@@ -836,7 +836,10 @@ impl Table {
     pub async fn uses_v2_manifest_paths(&self) -> napi::Result<bool> {
         self.inner_ref()?
             .as_native()
-            .ok_or_else(|| napi::Error::from_reason("This cannot be run on a remote table"))?
+            .ok_or_else(|| lancedb::Error::NotSupported {
+                message: "uses_v2_manifest_paths is not supported for remote tables.".into(),
+            })
+            .default_error()?
             .uses_v2_manifest_paths()
             .await
             .default_error()
@@ -846,7 +849,10 @@ impl Table {
     pub async fn migrate_manifest_paths_v2(&self) -> napi::Result<()> {
         self.inner_ref()?
             .as_native()
-            .ok_or_else(|| napi::Error::from_reason("This cannot be run on a remote table"))?
+            .ok_or_else(|| lancedb::Error::NotSupported {
+                message: "migrate_manifest_paths_v2 is not supported for remote tables.".into(),
+            })
+            .default_error()?
             .migrate_manifest_paths_v2()
             .await
             .default_error()