Olivier
03/19/2026, 10:04 AM{
"name": "relatedassetsdata",
"type": "object[]",
"sort": false,
"facet": false,
"index": true,
"optional": true
},
{
"name": "relatedassetsdata.childobjecttid",
"type": "string[]",
"sort": false,
"facet": false,
"index": true,
"reference": "objects.id",
"optional": true
},
Writing to that collection when it is empty works with relatedassetsdata.childobjecttid being set or null, however when I try to update that same document with null relatedassetsdata.childobjecttid I'm getting:
Field `relatedassetsdata.childobjecttid` must have string value.
If I delete the document and resend the exact same payload, it works. But following updates will fail.
I want to add that my update do not change relatedassetsdata.childobjecttid: it is null at creation and remains null in my update.
Any idea what could be wrong? Should I issue a bug report?Fanis Tharropoulos
03/19/2026, 10:42 AMOlivier
03/19/2026, 1:14 PM#!/bin/bash
### Typesense Bug Reproduction: Optional Reference in Nested Object Array ########
# Bug: Can't update documents with optional relations on nested object member fields
# When updating a document where a nested optional reference field is null,
# Typesense throws: "Field `fieldname` must have string value"
# Even though the field is marked as optional and was null on creation
set -x
export TYPESENSE_API_KEY=xyz
export TYPESENSE_HOST=http://localhost:8108
# Clean slate
docker stop typesense-repro 2>/dev/null
docker rm typesense-repro 2>/dev/null
rm -rf "$(pwd)"/typesense-data-dir-repro
mkdir "$(pwd)"/typesense-data-dir-repro
# Start Typesense
docker run -d -p 8108:8108 --name typesense-repro \
-v"$(pwd)"/typesense-data-dir-repro:/data \
typesense/typesense:30.1 \
--data-dir /data \
--api-key=$TYPESENSE_API_KEY \
--enable-cors
# Wait for Typesense to be ready
until curl -s -o /dev/null -w "%{http_code}" "$TYPESENSE_HOST/health" -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" | grep -q "200"; do
echo "Waiting for Typesense..."
sleep 2
done
echo "=== Typesense Ready ==="
curl -s "$TYPESENSE_HOST/debug" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" | jq
# Step 1: Create referenced collection (represents the target of the reference)
echo ""
echo "=== Step 1: Creating 'objects' collection (referenced collection) ==="
curl -s "$TYPESENSE_HOST/collections" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"name": "objects",
"fields": [
{"name": "title", "type": "string" },
{"name": "code", "type": "string" }
]
}' | jq
# Add a sample object document
echo ""
echo "=== Adding sample document to 'objects' collection ==="
curl -s "$TYPESENSE_HOST/collections/objects/documents" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{"id": "obj-123", "title": "Sample Object", "code": "OBJ001"}' | jq
# Step 2: Create main collection with nested object array containing optional reference
echo ""
echo "=== Step 2: Creating 'items' collection with nested optional reference ==="
curl -s "$TYPESENSE_HOST/collections" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"name": "items",
"enable_nested_fields": true,
"fields": [
{"name": "recordidentifier", "type": "string" },
{"name": "title", "type": "string" },
{"name": "relatedassetsdata", "type": "object[]", "optional": true },
{"name": "relatedassetsdata.id", "type": "int32[]", "optional": true },
{"name": "relatedassetsdata.relationtype", "type": "string[]", "optional": true },
{"name": "relatedassetsdata.childobjectid", "type": "string[]", "reference": "objects.id", "optional": true }
]
}' | jq
# Step 3: Create initial document with null optional reference field
echo ""
echo "=== Step 3: Creating document with NULL optional reference field (SHOULD WORK) ==="
curl -s "$TYPESENSE_HOST/collections/items/documents" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"id": "item-001",
"recordidentifier": "REC001",
"title": "Test Item with Null Reference",
"relatedassetsdata": [
{
"id": 1,
"relationtype": "Related",
"childobjectid": null
}
]
}' | jq
# Verify document was created
echo ""
echo "=== Verifying document was created successfully ==="
curl -s "$TYPESENSE_HOST/collections/items/documents/item-001" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" | jq
# Step 4: Update the document (keeping the reference field as null)
echo ""
echo "=== Step 4: Updating document with NULL optional reference UNCHANGED (BUG: SHOULD WORK BUT FAILS) ==="
echo "Expected: Success (field is optional and remains null)"
echo "Actual: Error - 'Field must have string value'"
echo ""
curl -s "$TYPESENSE_HOST/collections/items/documents/item-001" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"title": "Updated Test Item - Reference Still Null",
"relatedassetsdata": [
{
"id": 1,
"relationtype": "Related",
"childobjectid": null
}
]
}' | jq
# Step 5: Show that DELETE and re-INSERT works
echo ""
echo "=== Step 5: Deleting document ==="
curl -s "$TYPESENSE_HOST/collections/items/documents/item-001" \
-X DELETE \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" | jq
echo ""
echo "=== Step 6: Re-inserting EXACT SAME document (WORKS) ==="
curl -s "$TYPESENSE_HOST/collections/items/documents" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"id": "item-001",
"recordidentifier": "REC001",
"title": "Updated Test Item - Reference Still Null",
"relatedassetsdata": [
{
"id": 1,
"relationtype": "Related",
"childobjectid": null
}
]
}' | jq
# Step 7: Demonstrate that updating WITH a valid reference works
echo ""
echo "=== Step 7: Creating document WITH valid reference ==="
curl -s "$TYPESENSE_HOST/collections/items/documents" \
-X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"id": "item-002",
"recordidentifier": "REC002",
"title": "Test Item with Valid Reference",
"relatedassetsdata": [
{
"id": 2,
"relationtype": "Related",
"childobjectid": "obj-123"
}
]
}' | jq
echo ""
echo "=== Step 8: Updating document that HAS a valid reference (SHOULD WORK) ==="
curl -s "$TYPESENSE_HOST/collections/items/documents/item-002" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-d '{
"title": "Updated - Still has valid reference",
"relatedassetsdata": [
{
"id": 2,
"relationtype": "Related",
"childobjectid": "obj-123"
}
]
}' | jq
# Cleanup
echo ""
echo "=== Cleanup ==="
docker stop typesense-repro
docker rm typesense-repro
### Documentation ######################################################################################
# This script demonstrates a bug where optional reference fields in nested object arrays
# cannot be updated when they are null, even though they are marked as optional.
# The error only occurs on UPDATE operations, not on initial CREATE operations.Olivier
03/23/2026, 1:01 PMFanis Tharropoulos
03/23/2026, 4:14 PMOlivier
03/27/2026, 2:01 PMFanis Tharropoulos
03/30/2026, 9:45 AMOlivier
04/09/2026, 8:43 AMOlivier
04/13/2026, 4:56 PMFanis Tharropoulos
04/14/2026, 9:06 AMOlivier
04/14/2026, 3:27 PMFanis Tharropoulos
04/15/2026, 8:02 AMOlivier
04/21/2026, 12:40 PMAlan Martini
05/20/2026, 2:01 PM