hook-adapter-oracle: dropping context beyond

Error message

hook-adapter-oracle: dropping context beyond {MAX_HOST_CONTEXT_BYTES} bytes

What it means

The oracle hook adapter caps the total size of additional context forwarded to the hook at MAX_HOST_CONTEXT_BYTES. When a hook reply contains an additional_context string that would push the accumulated context over that cap, push_context refuses it and the adapter logs this warning and silently drops that context entry. This is a protective limit to bound host memory/payload size, not a hard failure — processing continues with truncated context.

Solutions

Reduce the size of the additional_context payload in the hook reply (truncate or summarize before returning it).
Raise MAX_HOST_CONTEXT_BYTES in capsule-hook-adapter-oracle if the cap is genuinely too small for your workload and host limits allow.
Send only the most relevant context: filter or rank context entries in the hook implementation so the important ones are pushed first.
Check earlier log lines to see which reply/topic contributed the oversized context and fix that producer.

Example fix

// before
let context = build_full_debug_dump(); // multi-MB string
reply.additional_context = Some(context);
// after
let context = build_full_debug_dump();
reply.additional_context = Some(truncate_to_bytes(&context, MAX_HOST_CONTEXT_BYTES / 4));

Defensive patterns

Strategy: validation

Validate before calling

// Rust (hook reply producer)
const MAX_HOST_CONTEXT_BYTES: usize = 8 * 1024;
fn context_fits(current_bytes: usize, next: &str) -> bool {
    current_bytes + next.len() <= MAX_HOST_CONTEXT_BYTES
}
assert!(context_fits(acc_bytes, &context), "additional_context would exceed byte cap");

Prevention

Truncate or summarize large context payloads before attaching them to hook replies.
Budget context bytes across all capsules contributing to one hook dispatch.
Monitor for this warning in logs; repeated occurrences indicate producers need smaller payloads.

When it happens

Trigger: Occurs in collect_additional_context (invoked from dispatch_oracle_hook) when parsing hook replies: a reply's 'additional_context' field is a non-empty string but the cumulative context_bytes already accumulated plus this context's size exceeds MAX_HOST_CONTEXT_BYTES, so push_context returns false.

Common situations: Developers attaching large blobs (logs, file dumps, large JSON payloads) as additional_context in oracle hook replies; multiple hook replies each adding context until the aggregate cap is hit; underestimating the byte budget when several capsules contribute context to one hook dispatch.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/61889faf878ee866. Report an issue: GitHub.

Appendix: source

Thrown at capsules/capsule-hook-adapter-oracle/src/lib.rs:293

                }
                for message in poll.messages {
                    if message.topic != reply_topic
                        || message.principal.verified() != Some(principal)
                    {
                        log::warn(format!(
                            "hook-adapter-oracle: dropping mismatched context reply on {reply_topic}"
                        ));
                        continue;
                    }
                    match serde_json::from_str::<serde_json::Value>(&message.payload) {
                        Ok(value) => {
                            if let Some(context) = value
                                .get("additional_context")
                                .and_then(serde_json::Value::as_str)
                                .filter(|context| !context.trim().is_empty())
                                && !push_context(&mut contexts, &mut context_bytes, context)
                            {
                                log::warn(format!(
                                    "hook-adapter-oracle: dropping context beyond {MAX_HOST_CONTEXT_BYTES} bytes"
                                ));
                            }
                        }
                        Err(error) => log::warn(format!(
                            "hook-adapter-oracle: dropping malformed reply on {reply_topic}: {error}"
                        )),
                    }
                }
            }
            Err(SysError::HostError(message)) if message.contains("Timeout") => break,
            Err(error) => return Err(error),
        }
    }
    if contexts.is_empty() {
        Ok(None)
    } else {
        Ok(Some(contexts.join("\n\n")))

View on GitHub (pinned to f6f22024fb)