debug

Cyoda Debug and Observation

Reading connection config:

PROFILE=$(jq -r '.active // "default"' "$HOME/.config/cyoda/cyoda-plugin-config.json" 2>/dev/null || echo "default"); jq --arg p "$PROFILE" '.profiles[$p] // {"endpoint":"none"}' "$HOME/.config/cyoda/cyoda-plugin-config.json" 2>/dev/null || echo '{"endpoint":"none"}'

Auth error rule: If any API call returns 401 or 403, invoke cyoda:auth to refresh the token, then retry the request once. If the retry also fails, surface the error to the user. Do not retry on any other error code.

Are you debugging a problem or observing entity history?

---

Debugging Mode

Identify the failure category and follow the relevant path:

Failed Transition

1. Fetch the entity and check current state:

curl -sf $AUTH "${ENDPOINT}/api/entity/${ENTITY_ID}"

2. Check if the transition is valid from the current state (compare against workflow definition)
3. Check criteria: if the transition has criteria, evaluate them manually
4. Look at entity changes for previous errors:

curl -sf $AUTH "${ENDPOINT}/api/entity/${ENTITY_ID}/changes"

5. If a processor is attached, check processor execution logs

Processor Error

1. Check gRPC connectivity: is your compute node registered?
2. Check tag routing: do the node's registered tags form a superset of the transition's required tags?
3. Check timeout: did the processor respond within 60s? If the operation legitimately takes longer, implement the fully async pattern.
4. Check response format: does it include requestId and entityId?
5. Check idempotency: is the processor handling duplicate requestId correctly?
6. For reconnection patterns and keep-alive implementation, see cyoda/skills/compute/resources/grpc-patterns.md.

Schema Rejection

1. Check schema mode: discover (widening) vs lock (strict)
2. In discover mode: type conflicts cause polymorphic fields — check what happened
3. In lock mode: compare incoming entity fields against the locked schema
4. Use /cyoda:docs for schema management API details

Connectivity Issues

1. Check ~/.config/cyoda/cyoda-plugin-config.json has correct endpoint value
2. For cloud: check token is not expired — re-run /cyoda:auth if needed
3. Test endpoint directly:

PROFILE=$(jq -r '.active // "default"' "$HOME/.config/cyoda/cyoda-plugin-config.json" 2>/dev/null || echo "default")
ENDPOINT=$(jq -r --arg p "$PROFILE" '.profiles[$p].endpoint // "none"' "$HOME/.config/cyoda/cyoda-plugin-config.json")
curl -sf --max-time 5 "${ENDPOINT}/readyz" || echo "UNREACHABLE"

---

Observation Mode

Investigate an entity's history for audit, compliance, or investigation purposes.

Browse entity lifecycle:

PROFILE=$(jq -r '.active // "default"' "$HOME/.config/cyoda/cyoda-plugin-config.json" 2>/dev/null || echo "default")
ENDPOINT=$(jq -r --arg p "$PROFILE" '.profiles[$p].endpoint // "none"' "$HOME/.config/cyoda/cyoda-plugin-config.json")
TOKEN=$(jq -r --arg p "$PROFILE" '.profiles[$p].token // ""' "$HOME/.config/cyoda/cyoda-plugin-config.json")
AUTH=$([ -n "$TOKEN" ] && echo "-H 'Authorization: Bearer $TOKEN'" || echo "")

# Entity change history
curl -sf $AUTH "${ENDPOINT}/api/entity/${ENTITY_ID}/changes"

Point-in-time state lookup:

# What state was this entity in at a specific time?
curl -sf $AUTH "${ENDPOINT}/api/entity/${ENTITY_ID}?pointInTime=2026-01-15T10:00:00Z"

Questions to answer with observation:

• Which transitions fired and when?
• Which processors ran for each transition?
• What was the entity's state at time T?
• Has this entity been in an error state before?

Before answering, invoke cyoda:docs to discover all available observation endpoints (audit trail, changes, point-in-time) and their query parameters. Use the endpoints as complementary sources — combine their results for a complete picture of the entity's history.

When investigating transactions or diagnosing failures, use ?level=DEBUG on the audit endpoint — it exposes step-by-step state machine execution detail: shard routing, TRANSACTION_EXEC events, each TRANSITION_MADE step, and actor identity per transaction.