The SDK's own errors carry gRPC-style codes, so a bad input reads as INVALID_ARGUMENT, not a worker bug

Four exception types in farm.query.vgi implement vgirpc's HasErrorCode
(WIRE_PROTOCOL §8) and subclass the JDK type each site threw before, so
existing catch clauses keep working. No error_kind is set.

- InvalidArgumentException (IllegalArgumentException, INVALID_ARGUMENT):
  every ParameterExtractor constraint, ScalarFn's type-bound check, an
  unparseable AT version/timestamp or unknown at_unit, an unsatisfiable
  implementation_version / data_version_spec.
- NotFoundException (IllegalArgumentException, NOT_FOUND): unknown
  function / aggregate / buffering function / scalar, a function not
  registered in the requested catalog or schema, unknown table in
  scan_function_get / scan_branches_get, InMemoryCatalog's missing
  schema / table / view, an AT version the table does not have.
- ReadOnlyCatalogException (UnsupportedOperationException,
  FAILED_PRECONDITION): DDL against a catalog that is not writable, from
  VgiServiceImpl.requireHosted and CatalogInterface's default refusals.
- UnimplementedException (UnsupportedOperationException, UNIMPLEMENTED):
  ADD/DROP COLUMN, which no catalog this SDK hosts supports.

The example worker's double() type rejection throws
InvalidArgumentException too, so both cross-SDK cases in
unary_error_propagation.test (double('abc') and sequence(10,
batch_size := 0)) now answer INVALID_ARGUMENT. Messages are unchanged.

JavaWorkerHttpConformanceTest asserts the decoded error_code end to end
through the vgi-rpc HTTP client for those two cases, an unknown function
(NOT_FOUND) and DDL on the read-only example catalog
(FAILED_PRECONDITION); SdkErrorCodesTest pins each type's code.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: rustyconover

vgi-example-worker/src/main/java/farm/query/vgi/example/scalar/DoubleFunction.java

@@ -2,6 +2,7 @@
 
 package farm.query.vgi.example.scalar;
 
+import farm.query.vgi.InvalidArgumentException;
 import farm.query.vgi.function.Arguments;
 import farm.query.vgi.function.TypeBoundPredicate;
 import farm.query.vgi.scalar.ScalarFn;
@@ -46,7 +47,7 @@ protected ArrowType outputType(Schema inputSchema, Arguments arguments) {
                 || in instanceof ArrowType.LargeUtf8
                 || in instanceof ArrowType.Binary
                 || in instanceof ArrowType.LargeBinary) {
-            throw new IllegalArgumentException(
+            throw new InvalidArgumentException(
                     "double: _is_multipliable_type rejects " + in
                             + " — only numeric types (int/float/decimal) are supported");
         }

vgi-example-worker/src/test/java/farm/query/vgi/example/client/AbstractVgiHttpConformanceTest.java

@@ -598,7 +598,7 @@ private static CatalogAttachRequest attachRequest() {
         return CatalogAttachRequest.of(CATALOG, new byte[0], "", "");
     }
 
-    private BindRequest tableBind(String function, byte[] arguments) {
+    protected BindRequest tableBind(String function, byte[] arguments) {
         return new BindRequest(
                 function, arguments, "TABLE",
                 null,                       // input_schema — producer mode

vgi-example-worker/src/test/java/farm/query/vgi/example/client/JavaWorkerHttpConformanceTest.java

@@ -2,8 +2,24 @@
 
 package farm.query.vgi.example.client;
 
+import farm.query.vgi.client.ArgumentsEncoder;
+import farm.query.vgi.client.SettingsEncoder;
+import farm.query.vgi.internal.SchemaUtil;
+import farm.query.vgi.protocol.BindRequest;
+import farm.query.vgirpc.RpcError;
+import farm.query.vgirpc.errors.Code;
+import org.apache.arrow.vector.types.pojo.ArrowType;
+import org.apache.arrow.vector.types.pojo.Field;
+import org.apache.arrow.vector.types.pojo.Schema;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
  * The Java leg of {@link AbstractVgiHttpConformanceTest}: the shared assertions
@@ -12,6 +28,11 @@
  * <p>Always runs — it needs nothing beyond this build — so a green Python leg
  * and a green Java leg together are what prove agreement, and a red one alone
  * names the side that is wrong.
+ *
+ * <p>It also pins the gRPC-style {@code error_code} the SDK puts on its own
+ * errors (vgi-rpc WIRE_PROTOCOL §8). That half is Java-only for now: the
+ * assertions are decoded from the wire by the vgi-rpc client, exactly as the
+ * DuckDB extension reads them.
  */
 final class JavaWorkerHttpConformanceTest extends AbstractVgiHttpConformanceTest {
 
@@ -31,4 +52,42 @@ static void stopWorker() {
     protected VgiHttpWorkerUnderTest worker() {
         return worker;
     }
+
+    /** {@code SELECT example.main.double('abc')}: a scalar's type rejection is the caller's fault. */
+    @Test
+    void scalarTypeRejectionIsInvalidArgument() {
+        Schema input = new Schema(List.of(Field.nullable("value", new ArrowType.Utf8())));
+        BindRequest bind = new BindRequest(
+                "double", ArgumentsEncoder.builder().encode(), "SCALAR",
+                SchemaUtil.serializeSchema(input), SettingsEncoder.builder().encode(), null,
+                handle, null, false, null, null, null, null, "main");
+        RpcError e = assertThrows(RpcError.class, () -> vgi.bind(bind, null));
+        assertEquals(Code.INVALID_ARGUMENT.name(), e.errorCode(), e.errorMessage());
+    }
+
+    /** {@code sequence(10, batch_size := 0)}: a failed argument constraint is the caller's fault. */
+    @Test
+    void argumentConstraintIsInvalidArgument() {
+        byte[] args = ArgumentsEncoder.builder().positional(10L).named("batch_size", 0L).encode();
+        RpcError e = assertThrows(RpcError.class, () -> vgi.bind(tableBind("sequence", args), null));
+        assertEquals(Code.INVALID_ARGUMENT.name(), e.errorCode(), e.errorMessage());
+        assertTrue(e.errorMessage().contains("must be >= 1"), e.errorMessage());
+    }
+
+    /** Binding a function the worker does not serve is a failed lookup. */
+    @Test
+    void unknownFunctionIsNotFound() {
+        RpcError e = assertThrows(RpcError.class, () -> vgi.bind(
+                tableBind("no_such_function_at_all", ArgumentsEncoder.positionalArgs(1L)), null));
+        assertEquals(Code.NOT_FOUND.name(), e.errorCode(), e.errorMessage());
+    }
+
+    /** DDL against the example catalog, which is not writable, is refused as a precondition. */
+    @Test
+    void ddlOnReadOnlyCatalogIsFailedPrecondition() {
+        RpcError e = assertThrows(RpcError.class, () -> vgi.catalog_schema_create(
+                handle, List.of("nope"), "error", null, java.util.Map.of(), null, null));
+        assertEquals(Code.FAILED_PRECONDITION.name(), e.errorCode(), e.errorMessage());
+        assertTrue(e.errorMessage().contains("read-only"), e.errorMessage());
+    }
 }

vgi/src/main/java/farm/query/vgi/CatalogInterface.java

@@ -310,7 +310,7 @@ default CatalogContentsResult catalogContents(CatalogContentsProvider.Request re
      * @return the exception
      */
     private UnsupportedOperationException readOnly(String method) {
-        return new UnsupportedOperationException(
+        return new ReadOnlyCatalogException(
                 "catalog " + name() + " is read-only: " + method + " not supported");
     }
 

vgi/src/main/java/farm/query/vgi/InvalidArgumentException.java

@@ -0,0 +1,44 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi;
+
+import farm.query.vgirpc.errors.Code;
+import farm.query.vgirpc.errors.HasErrorCode;
+
+/**
+ * The caller's input was wrong: an argument failed validation, had a bad value, or an argument or input column has a type the function rejects.
+ *
+ * <p>Reported on the wire with {@code error_code = INVALID_ARGUMENT} (vgi-rpc error model, WIRE_PROTOCOL
+ * §8), so a client can tell this failure from a worker bug. It extends
+ * {@link IllegalArgumentException}, the JDK type the SDK threw here before, so existing {@code catch} clauses
+ * keep working. No {@code error_kind} is set.
+ */
+public class InvalidArgumentException extends IllegalArgumentException implements HasErrorCode {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Build the error.
+     *
+     * @param message the human-readable message, reported verbatim
+     */
+    public InvalidArgumentException(String message) {
+        super(message);
+    }
+
+    /**
+     * Build the error with an underlying cause.
+     *
+     * @param message the human-readable message, reported verbatim
+     * @param cause the underlying failure
+     */
+    public InvalidArgumentException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /** @return {@link Code#INVALID_ARGUMENT} */
+    @Override
+    public Code errorCode() {
+        return Code.INVALID_ARGUMENT;
+    }
+}

vgi/src/main/java/farm/query/vgi/NotFoundException.java

@@ -0,0 +1,44 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi;
+
+import farm.query.vgirpc.errors.Code;
+import farm.query.vgirpc.errors.HasErrorCode;
+
+/**
+ * A lookup by name failed: no such function, table, schema, catalog, or other object.
+ *
+ * <p>Reported on the wire with {@code error_code = NOT_FOUND} (vgi-rpc error model, WIRE_PROTOCOL
+ * §8), so a client can tell this failure from a worker bug. It extends
+ * {@link IllegalArgumentException}, the JDK type the SDK threw here before, so existing {@code catch} clauses
+ * keep working. No {@code error_kind} is set.
+ */
+public class NotFoundException extends IllegalArgumentException implements HasErrorCode {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Build the error.
+     *
+     * @param message the human-readable message, reported verbatim
+     */
+    public NotFoundException(String message) {
+        super(message);
+    }
+
+    /**
+     * Build the error with an underlying cause.
+     *
+     * @param message the human-readable message, reported verbatim
+     * @param cause the underlying failure
+     */
+    public NotFoundException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /** @return {@link Code#NOT_FOUND} */
+    @Override
+    public Code errorCode() {
+        return Code.NOT_FOUND;
+    }
+}

vgi/src/main/java/farm/query/vgi/ReadOnlyCatalogException.java

@@ -0,0 +1,44 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi;
+
+import farm.query.vgirpc.errors.Code;
+import farm.query.vgirpc.errors.HasErrorCode;
+
+/**
+ * A write (DDL or DML) was sent to a catalog that is read-only.
+ *
+ * <p>Reported on the wire with {@code error_code = FAILED_PRECONDITION} (vgi-rpc error model, WIRE_PROTOCOL
+ * §8), so a client can tell this failure from a worker bug. It extends
+ * {@link UnsupportedOperationException}, the JDK type the SDK threw here before, so existing {@code catch} clauses
+ * keep working. No {@code error_kind} is set.
+ */
+public class ReadOnlyCatalogException extends UnsupportedOperationException implements HasErrorCode {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Build the error.
+     *
+     * @param message the human-readable message, reported verbatim
+     */
+    public ReadOnlyCatalogException(String message) {
+        super(message);
+    }
+
+    /**
+     * Build the error with an underlying cause.
+     *
+     * @param message the human-readable message, reported verbatim
+     * @param cause the underlying failure
+     */
+    public ReadOnlyCatalogException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /** @return {@link Code#FAILED_PRECONDITION} */
+    @Override
+    public Code errorCode() {
+        return Code.FAILED_PRECONDITION;
+    }
+}

vgi/src/main/java/farm/query/vgi/UnimplementedException.java

@@ -0,0 +1,44 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi;
+
+import farm.query.vgirpc.errors.Code;
+import farm.query.vgirpc.errors.HasErrorCode;
+
+/**
+ * An operation the SDK explicitly does not support.
+ *
+ * <p>Reported on the wire with {@code error_code = UNIMPLEMENTED} (vgi-rpc error model, WIRE_PROTOCOL
+ * §8), so a client can tell this failure from a worker bug. It extends
+ * {@link UnsupportedOperationException}, the JDK type the SDK threw here before, so existing {@code catch} clauses
+ * keep working. No {@code error_kind} is set.
+ */
+public class UnimplementedException extends UnsupportedOperationException implements HasErrorCode {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Build the error.
+     *
+     * @param message the human-readable message, reported verbatim
+     */
+    public UnimplementedException(String message) {
+        super(message);
+    }
+
+    /**
+     * Build the error with an underlying cause.
+     *
+     * @param message the human-readable message, reported verbatim
+     * @param cause the underlying failure
+     */
+    public UnimplementedException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /** @return {@link Code#UNIMPLEMENTED} */
+    @Override
+    public Code errorCode() {
+        return Code.UNIMPLEMENTED;
+    }
+}

vgi/src/main/java/farm/query/vgi/catalog/InMemoryCatalog.java

@@ -3,6 +3,7 @@
 package farm.query.vgi.catalog;
 
 import farm.query.vgi.CatalogInterface;
+import farm.query.vgi.NotFoundException;
 import farm.query.vgi.protocol.CatalogAttachRequest;
 import farm.query.vgi.protocol.SchemaInfo;
 import farm.query.vgi.protocol.TableCreateRequest;
@@ -204,7 +205,7 @@ public void schemaCreate(byte[] attachId, List<String> path, OnConflict onConfli
                 }
             }
             if (path.size() > 1 && !s.schemas.containsKey(key(path.subList(0, path.size() - 1)))) {
-                throw new IllegalArgumentException(
+                throw new NotFoundException(
                         "Schema " + String.join(".", path.subList(0, path.size() - 1)) + " not found");
             }
             s.schemas.put(key(path), new SchemaState(path, comment, tags));
@@ -219,7 +220,7 @@ public void schemaDrop(byte[] attachId, List<String> path, boolean ignoreNotFoun
             SchemaState schema = s.schemas.get(key(path));
             if (schema == null) {
                 if (ignoreNotFound) return;
-                throw new IllegalArgumentException("Schema " + String.join(".", path) + " not found");
+                throw new NotFoundException("Schema " + String.join(".", path) + " not found");
             }
             List<List<String>> doomed = new ArrayList<>();
             for (Map.Entry<List<String>, SchemaState> e : s.schemas.entrySet()) {
@@ -265,7 +266,7 @@ public void tableDrop(byte[] attachId, List<String> path, String name, boolean i
             SchemaState schema = s.schemas.get(key(path));
             if (schema == null || schema.tables.remove(name) == null) {
                 if (ignoreNotFound) return;
-                throw new IllegalArgumentException("Table " + name + " not found in schema " + String.join(".", path));
+                throw new NotFoundException("Table " + name + " not found in schema " + String.join(".", path));
             }
             s.version++;
         }
@@ -291,7 +292,7 @@ public void viewDrop(byte[] attachId, List<String> path, String name, boolean ig
             SchemaState schema = s.schemas.get(key(path));
             if (schema == null || schema.views.remove(name) == null) {
                 if (ignoreNotFound) return;
-                throw new IllegalArgumentException("View " + name + " not found in schema " + String.join(".", path));
+                throw new NotFoundException("View " + name + " not found in schema " + String.join(".", path));
             }
             s.version++;
         }
@@ -311,7 +312,7 @@ private State state(byte[] attachId) {
 
     private static SchemaState requireSchema(State s, List<String> path) {
         SchemaState schema = s.schemas.get(key(path));
-        if (schema == null) throw new IllegalArgumentException("Schema " + String.join(".", path) + " not found");
+        if (schema == null) throw new NotFoundException("Schema " + String.join(".", path) + " not found");
         return schema;
     }