GraphQL MessageType crashes when stored messages omit code (get_shipments returns data: null)

[minchaminder]

Upstream report: GraphQL MessageType fails when stored messages omit code

Target: karrioapi/karrio
Type: Bug report (GitHub Issues disabled — post as Q&A Discussion)
Affects: v2026.1.32 (main) and likely earlier releases
Severity: High — entire get_shipments page returns data: null

---

Summary

The GraphQL MessageType resolver crashes when deserializing carrier messages that omit the code field. This is valid per the SDK and normal storage behavior (lib.to_dict strips null keys), but GraphQL treats code as required at init time despite being declared Optional[str].

Result: dashboard shipments list shows "No shipment found" even when thousands of shipments exist.

---

Symptoms

GraphQL response (HTTP 200):

{
  "data": null,
  "errors": [{
    "message": "MessageType.__init__() missing 1 required keyword-only argument: 'code'",
    "path": ["shipments", "edges", 2, "node", "messages"]
  }]
}

One bad message on one shipment in the page aborts the entire connection.

---

Root cause

File: modules/graph/karrio/server/graph/schemas/base/types.py

@strawberry.type
class MessageType:
    carrier_name: typing.Optional[str]      # no default
    carrier_id: typing.Optional[str]       # no default
    message: typing.Optional[str]          # no default
    code: typing.Optional[str]             # no default  ← problem
    details: typing.Optional[utils.JSON] = None

    @staticmethod
    def parse(charge: dict):
        return MessageType(
            **{k: v for k, v in charge.items() if k in MessageType.__annotations__}
        )

ChargeType in the same file already uses = None defaults correctly.

Why code is absent in stored JSON

1. SDK (karrio.core.models.Message): code: str = None — optional
2. Persistence (lib.to_dict in modules/sdk/karrio/core/utils/dict.py): strips keys where value is None
3. Stored shipment.messages JSON often has no code key at all

This is not hypothetical — observed in production with 401 message rows missing code (all from freightcom_rest rate/customs errors). Any carrier/plugin that omits code triggers the same GraphQL failure.

---

Suggested fix

Make optional fields truly optional for Strawberry (match ChargeType):

@strawberry.type
class MessageType:
    carrier_name: typing.Optional[str] = None
    carrier_id: typing.Optional[str] = None
    message: typing.Optional[str] = None
    code: typing.Optional[str] = None
    details: typing.Optional[utils.JSON] = None

    @staticmethod
    def parse(msg: dict):
        return MessageType(
            **{k: msg.get(k) for k in MessageType.__annotations__}
        )

Also affects TrackerType.messages and ManifestType.messages (same MessageType.parse).

Regression test

def test_parse_message_without_code(self):
    msg = {
        "level": "error",
        "message": "bad or missing data",
        "carrier_id": "freightcomRest",
        "carrier_name": "freightcom_rest",
    }
    parsed = MessageType.parse(msg)
    self.assertIsNone(parsed.code)

---

Scope

In scope	Out of scope
GraphQL deserialization robustness	freightcom_rest not setting code at source (separate improvement)
Align GraphQL with SDK/storage contract	Changing lib.to_dict null-stripping behavior
Tracker/manifest message fields	Frontend empty-state UX (optional follow-up)

---

Reproduction

1. Create or find a shipment with messages JSON missing code:

{
  "level": "error",
  "message": "bad or missing data: customs_data.products[0].hsverified: ...",
  "carrier_id": "freightcomRest",
  "carrier_name": "freightcom_rest",
  "details": { "details.customs_data.products[0].hsverified": "..." }
}

2. Query get_shipments including messages on that shipment
3. Observe GraphQL error above and data: null

---

References

• SDK Message model: modules/sdk/karrio/core/models.py
• lib.to_dict null stripping: modules/sdk/karrio/core/utils/dict.py
• Shipment serializer saves messages via lib.to_dict: modules/manager/karrio/server/manager/serializers/shipment.py

---

Offer

Happy to submit a PR if maintainers prefer — we have a working patch and regression test ready on a fork.