Troubleshooting

Common Twilic integration issues and how to resolve them.

Decode errors

failed to decode v2 payload

Causes: Truncated bytes, wrong format (MessagePack/JSON sent to Twilic decoder), v1 payload to v2 decoder.

Fix:

# Inspect bytes
cat payload.twilic | twilic decode --pretty

# Check first byte / magic
xxd payload.twilic | head -1

Verify producer and consumer agree on v2 and the same profile.

TwilicDecodeError: DECODE_DEPTH_EXCEEDED

Cause: Payload nesting exceeds decode depth limit (default 64).

Fix: Reject malformed input. If legitimate, inspect for accidental recursive structures. Do not disable limits on untrusted input.

decode count limit exceeded

Cause: Corrupt length prefix or malicious oversized array/map declaration.

Fix: Validate payload size before decode. Check for transport corruption (partial reads on TCP without length framing).

Stateful session issues

Patches fail after reconnect

Cause: Client or server lost session state.

Fix:

enc.reset();
socket.send(enc.encode(fullState)); // full frame first
// then resume encodePatch()

StatelessRetryRequired / ErrStatelessRetryRequired

Cause: Decoder received patch referencing unknown base ID or shape.

Fix: Set unknownReferencePolicy: "statelessRetry" and implement full-frame retry. Or call reset() on producer.

Patch size not shrinking

Cause: Most fields change every tick, or session was reset silently.

Fix: Verify with transport-JSON logging. If > 50% of fields change per tick, stateful mode may not help.

HTTP integration issues

415 Unsupported Media Type

Cause: Request missing Content-Type: application/vnd.twilic.

Fix:

// Client
headers: { "Content-Type": "application/vnd.twilic" }

// Or relax on server (internal only)
twilicParser({ requireContentType: false })

Empty or corrupt request body

Cause: express.json() consumed the stream before twilicParser().

Fix: Isolate Twilic routes on a separate router without JSON middleware. See Express integration.

Client receives binary gibberish

Cause: Client expects JSON but server sends Twilic.

Fix: Set Accept: application/vnd.twilic or use @twilic/fetch / @twilic/axios.

JavaScript-specific

init() not called

Symptom: Error about backend not initialized.

Fix:

await init(); // once at startup

Precision loss on large integers

Symptom: IDs change after roundtrip.

Fix: Use bigint:

{
  id: 9007199254740993n;
} // not Number

Wrong import path

Symptom: encodeBatch is not a function from @twilic/core.

Fix: Import batch functions from @twilic/core/advanced:

import { encodeBatch } from "@twilic/core/advanced";

Size not improving vs MessagePack

Causes:

• Single non-repeating objects (expected — Twilic ≈ MessagePack)
• Batch size too small (< 10 records)
• Heterogeneous shapes mixed in one batch

Fix: Batch same-shape records. Measure at 50–256 records. See Batch & Columnar.

Debugging tools

Tool	Use
Twilic CLI	encode / decode roundtrip
Playground	Interactive size comparison
decodeToTransportJson()	Inspect wire content (advanced)
xxd / hex dump	Raw byte inspection

echo '{"a":1}' | twilic encode | twilic decode --pretty

Getting help

1. Reproduce with minimal payload via CLI
2. Note SDK language + version + profile used
3. Include encode/decode code path (main vs advanced import)
4. Open issue at github.com/twilic/twilic with redacted payload bytes

Related

• Errors & Limits
• Security
• FAQ