gastownhall/beads · error

serializing waits-for metadata: %w

Error message

serializing waits-for metadata: %w

What it means

After validating the gate, normalizeApplyEdgeMetadata re-marshals the WaitsForMeta struct to canonical JSON. This error wraps a json.Marshal failure, which is practically unreachable for WaitsForMeta (no channels/funcs/cycles) but is defensively reported if serialization fails.

Source

Thrown at internal/storage/batch_apply.go:389

		}
		return metadata, nil
	}
	meta := types.WaitsForMeta{}
	if trimmed != "" && trimmed != "{}" {
		if err := json.Unmarshal([]byte(trimmed), &meta); err != nil {
			return "", fmt.Errorf("waits-for metadata is not a well-formed gate object: %w", err)
		}
	}
	if meta.Gate == "" {
		meta.Gate = types.WaitsForAllChildren
	}
	if !types.IsValidWaitsForGate(meta.Gate) {
		return "", fmt.Errorf("waits-for gate %q is neither %q nor %q",
			meta.Gate, types.WaitsForAllChildren, types.WaitsForAnyChildren)
	}
	raw, err := json.Marshal(meta)
	if err != nil {
		return "", fmt.Errorf("serializing waits-for metadata: %w", err)
	}
	return string(raw), nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Report as a library bug if seen with stock types
2. Check for a custom MarshalJSON on WaitsForMeta or its fields that returns an error
3. Verify the types version matches what the storage layer expects

if err != nil && strings.Contains(err.Error(), "serializing waits-for metadata") {
	return fmt.Errorf("library bug: canonicalizing waits-for metadata failed: %w", err)
}

When it happens

Trigger: json.Marshal of the populated WaitsForMeta returns an error — only possible if the type gains unsupported fields (e.g. channel, func, or cyclic data) or a custom MarshalJSON misbehaves.

Common situations: Essentially never hit by users; would appear after a library change to WaitsForMeta or a custom marshaler bug.

Related errors

• serializing waits-for metadata: %w
• serializing waits-for also_blocks metadata: %w
• failed to marshal backup state: %w
• failed to marshal issue %s: %w
• failed to write JSON: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a241d48abbfd1b00. Report an issue: GitHub.