Design your device shadow schema to fit within the 8 KB limit that applies to the entire shadow document.
Retrieve the current shadow via GET /things/YOUR_THING_NAME/shadow to inspect its current size.
Update the shadow by publishing to the $aws/things/YOUR_THING_NAME/shadow/update MQTT topic or via the REST API with a partial state document.
Monitor the shadow's reported and desired sections and prune stale or redundant keys to remain within the size cap.
For devices requiring larger state, consider splitting state across named shadows (classic unnamed plus additional named shadows).
Subscribe to $aws/things/YOUR_THING_NAME/shadow/update/rejected to detect and handle update failures including size violations.
Known gotchas
The 8 KB size limit applies to the entire shadow document as a whole — not per section (desired, reported, delta) — so all sections combined must fit within 8 KB.
Named shadows each have their own 8 KB limit, so splitting state across multiple named shadows is a valid strategy for devices with large state requirements.
AWS may reject updates silently on the /update topic without a visible error if you are not subscribed to the /update/rejected topic.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp