unicity-aos/aos-ce · error
Subscribe ` ` has priority outside the u32 range.
Error message
Subscribe `{key}` has priority outside the u32 range. What it means
During manifest validation, capsule-forge checks each [subscribe] entry's `priority` field against the u32 range (0..=4294967295) because the tool bus dispatches messages by priority-ordered queueing backed by u32. A value outside that range (e.g. negative or > u32::MAX) cannot be represented and would corrupt ordering, so the check fails the manifest.
Solutions
- Clamp or change the priority value in the [subscribe] entry to an integer in 0..4294967295.
- Remember lower values run first; re-scale your priority scheme to fit the u32 range.
- Re-run the manifest validation to confirm the finding clears.
Example fix
// before ([subscribe])
"tool.v1.request.describe" = { wit = ..., handler = "tool_describe", priority = 5000000000 }
// after
"tool.v1.request.describe" = { wit = ..., handler = "tool_describe", priority = 100 } Defensive patterns
Strategy: validation
Validate before calling
// Rust: check before writing the manifest
fn valid_priority(p: i64) -> bool { (0..=u32::MAX as i64).contains(&p) }
assert!(valid_priority(100)); Type guard
fn as_u32_priority(v: &serde_json::Value) -> Option<u32> {
v.as_i64().filter(|p| (0..=u32::MAX as i64).contains(p)).map(|p| p as u32)
} Prevention
- Define priorities as u32 constants instead of literals in templates.
- Add a CI lint that rejects priority values outside 0..=4294967295.
- Document the u32 limit and 'lower runs first' rule next to the manifest schema.
When it happens
Trigger: Running `capsule-forge validate` (validate_manifest -> check_tool_bus) when a `[subscribe]` entry sets `priority = <integer>` that is negative or greater than 4294967295.
Common situations: Copy-pasting priority values from documentation of other systems using i64 priorities, computing priority via arithmetic that overflows, or hand-editing the manifest and typing an extra digit.
Understand the failure class
Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.
Related errors
- Subscribe ` ` priority must be an integer.
- Subscribe ` ` has no `handler`.
- Mandatory publish key
- Subscribe `tool.v1.request.describe` is missing — tools…
- Topic ` ` has empty segments (leading/trailing/consecutive…
AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13).
Data as JSON: /api/errors/6359a277f1351157.
Report an issue: GitHub.
Appendix: source
Thrown at capsules/capsule-forge/src/checks.rs:241
let sub_table = root.get("subscribe").and_then(Toml::as_table);
let mut saw_execute_tool = false;
for key in sub_keys {
if let Some(entry) = sub_table.and_then(|table| table.get(key)) {
let has_handler = entry
.get("handler")
.and_then(Toml::as_str)
.is_some_and(|handler| !handler.is_empty());
if entry.get("priority").is_some() && !has_handler {
out.push(Finding::err(
format!("Subscribe `{key}` sets `priority` without a `handler`."),
"Add a real handler binding or remove priority from the ACL-only subscription.",
));
}
if let Some(priority) = entry.get("priority") {
if let Some(priority) = priority.as_integer() {
if !(0..=u32::MAX.into()).contains(&priority) {
out.push(Finding::err(
format!("Subscribe `{key}` has priority outside the u32 range."),
"Use an integer from 0 through 4294967295; lower values run first.",
));
}
} else {
out.push(Finding::err(
format!("Subscribe `{key}` priority must be an integer."),
"Use an integer from 0 through 4294967295; lower values run first.",
));
}
}
}
let Some(tool) = key.strip_prefix("tool.v1.execute.") else {
continue;
};
// The `*.result` publish key would also strip; skip non-tool shapes.
if tool.contains('*') || tool.contains('.') {View on GitHub (pinned to f6f22024fb)