Troubleshooting & Error Reference

Most issues can be resolved by checking mode, freshness, licences, and Findings. Use this page to map warnings to actions.

UI Warnings (What To Do and Why)

Findings: WARN

Why you see it: WatchCrux detected a minor issue e.g., a small version mismatch between services, a temporary performance spike, or a non‑critical metric outside its usual range. Your answer is still produced with receipts; platform health is just not perfect.

What to do now: You can usually proceed. If timing allows, re‑run later or switch to Audit for critical decisions. If you repeatedly see WARN, save the answer and include the Findings note in any downstream review so others understand the context.

How to prevent it: Avoid heavy loads during maintenance windows; keep SDKs up to date; prefer Verified over Light for work you’ll share.

Findings: FAIL

Why you see it: A material integrity check failed e.g., missing mandatory metrics, an incompatible SDK, or a health probe that couldn’t verify a dependency. In this state the platform can’t guarantee its usual trust properties.

What to do now: Don’t rely on the result. Save your query, then re‑run later. If a deadline forces you to proceed, add a visible disclaimer and open a Dispute to trigger operator review.

How to prevent it: Keep to supported SDK ranges; avoid backgrounding long processes; monitor product status if you depend on strict SLAs.

Stale Snapshot

Why you see it: Your request asked for evidence newer than what is currently in the corpus (e.g., freshness set to 7 days but sources are older). Freshness is a guardrail against outdated facts.

What to do now: Widen the freshness window (e.g., 30 days) or request a re‑crawl. For time‑critical topics, prefer Verified or Audit so the system works harder to find recent evidence.

How to prevent it: Set realistic freshness based on the domain (policy updates vs. historical research); schedule periodic refreshes for ongoing work.

Licence Incompatible

Why you see it: A cited source’s licence doesn’t allow the reuse you requested (e.g., non‑commercial or no‑derivatives content used in a commercial export).

What to do now: Keep the citation for transparency, but choose alternate sources for reuse. The Licences guide lists what each badge allows.

How to prevent it: Prefer CC-BY, OGL, or public-domain sources when you plan to republish; check licence badges in the Why Trust panel before exporting.

Not Enough Independent Sources

Why you see it: Verified/Audit aim for domain diversity. Sometimes a topic has only one authoritative source; other times your phrasing steered retrieval toward a single venue.

What to do now: Try alternative wording, ask for broader scope, or switch to Audit. If only one credible source exists (e.g., an official registry), the UI will say so explicitly you can still proceed with that caveat.

How to prevent it: Include hints in your question (e.g., “official registry + independent analysis”), and avoid biasing toward one publication.

Why you see it: The counterfactual lane found credible disagreement e.g., an update that supersedes an older article, or two datasets with different methodologies.

What to do now: Read both citations, check timestamps, and note the reason for the conflict. For decisions that matter, re‑run in Audit and include a short note explaining which source you chose and why.

How to prevent it: You can’t prevent disagreement, but you can plan for it always check the Why Trust panel when topics are contentious.

Network / Rate / Limits

Rate Limited

Why you see it: You or your organisation sent too many requests in a short time. To keep the system fair and predictable, C³ applies per‑mode and per‑org rate guards.

What to do now: Wait for the Retry‑After window, then try again. If this blocks a workflow, reduce parallelism or batch requests.

How to prevent it: Stagger calls, cache results where appropriate, and avoid firing Audit runs in large bursts.

Timeout

Why you see it: The Engine couldn’t respond within the configured time common during spikes, when Audit mode is busy assembling counterfactuals, or when a downstream dependency slows.

What to do now: Retry once or twice with backoff. Check Findings; if WARN/FAIL persists, postpone or switch to Verified with a smaller k.

How to prevent it: Set sensible timeouts in your client; choose Verified for exploratory work; run Audit only when you need the extra guarantees.

Dispute vs Revision

Use Revision when the foundations are solid sources verify and licences are fine but the write‑up needs clarification, a missing scope detail, or a better example. A revision should keep the same citations and receipt lineage.

Use a Dispute when trust is at risk missing citations, failed signatures, incompatible licences, or clear scope breaches. Disputes trigger an operator review: receipts are replayed, rules are checked, and outcomes range from a targeted fix to a partial or full refund.

See the Disputes & Refunds guide for typical timelines and outcomes.

Short Error Map (Developers)

Contradiction Counterfactuals unresolved. Show a clear banner and let the user compare sources; offer Audit for strict runs.
StaleSnapshot Freshness window exceeded. Prompt to widen the window or request a refresh job; display the oldest citation timestamp.
RateLimited Too many requests. Back off with jitter; show remaining time to users where possible.
LicenceIncompatible Licence doesn’t match the requested export. Render a warning, list compatible alternatives, and keep the citation.