fix(candid): improve error messages for candid decoding errors

CHANGELOG.md

@@ -14,6 +14,7 @@
 - refactor(agent): extract `readCertifiedReject` helper to deduplicate certified reject logic
 - refactor(agent): make `CallContext.httpDetails` optional for polling error paths
 - feat(agent): add `rawCertificate` to `pollForResponse` return type and export `PollForResponseResult`
+- fix(candid): improve error messages for candid decoding errors in Variant types
 
 ## [5.0.0] - 2025-12-18
 

packages/core/src/candid/idl.test.ts

@@ -519,6 +519,15 @@ test('decode / encode unknown variant', () => {
   expect(reencoded).toEqual(encoded);
 });
 
+test("decode variant with unknown field hash throws descriptive error", () => {
+  // Encode {ok: "good"} with variant {ok: Text, err: Text}
+  const encoded = hexToBytes("4449444c016b029cc20171e58eb4027101000004676f6f64");
+  // Decode with a variant that does not include "ok" or "err"
+  const MismatchedVariant = IDL.Variant({ foo: IDL.Text });
+  expect(() => IDL.decode([MismatchedVariant], encoded)).toThrow(/Cannot find field hash/);
+  expect(() => IDL.decode([MismatchedVariant], encoded)).toThrow(/expected fields: \[foo\]/);
+});
+
 test('throw on serializing unknown', () => {
   expect(() => IDL.encode([IDL.Unknown], ['test'])).toThrow('Unknown cannot be serialized');
 });

packages/core/src/candid/idl.ts

@@ -1566,7 +1566,10 @@ export class VariantClass extends ConstructType<Record<string, any>> {
         return { [key]: value };
       }
     }
-    throw new Error(`Cannot find field hash ${wireHash}`);
+    const expectedFields = this._fields.map(([name]) => name).join(', ');
+    throw new Error(
+      `Cannot find field hash ${wireHash} in variant, expected fields: [${expectedFields}]`,
+    );
   }
 
   get name() {