Troubleshooting

Troubleshooting starts from observable evidence: the operation status, failing action, typed error, executor capability, device output, and reported facts. Avoid repeating a destructive operation until the failed boundary is understood.

Start with the evidence you have

• SenCmd alias, code, response, or event: find the command for the exact SenCore release.
• SenCLI setup, credential, context, device access, or JSON problem: use SenCLI troubleshooting.
• Operation status or typed error: open the Device Operation Reference.
• Project component or hardware selection: inspect the project through SenHub Web or use the relevant SenCLI project commands.
• Unknown term or identity: check the glossary before changing a project or device.

Triage order

1. Confirm the SenHub environment, project, device, SenCore release, component-definition revision, Application, and artifact identities.
2. Inspect the DeviceOperationPlan action that failed and the executor capability it requires.
3. Preserve operation events, device logs, and reported facts.
4. Resolve connectivity, permissions, local device access, artifact integrity, or protocol mismatch at the boundary that reported it.
5. Retry only when the plan permits retry or create a new intent after the underlying facts change.

Boundary matrix

Symptom	First evidence	Likely boundary	Safe next action
Board is not detected	Port list, browser permission, executor capability	Local executor or physical connection	Close competing serial tools, reconnect the board, and rerun target inspection
Plan waits for an executor	Required capability and executor heartbeat	Web/CLI availability	Start the selected executor and confirm it reports the required capability
Target facts changed	Expected versus reported Board/chip facts	Hardware identity	Stop; select the exact Board or create a new intent for the changed target
Artifact digest mismatch	Expected digest, downloaded digest, operation ID	Artifact supply chain	Discard the unverified file and re-resolve the published artifact
Board mismatch	Board reference and reported chip/flash facts	Catalog compatibility	Do not flash; correct the project Board or publish a correct Catalog definition
Device command failed	Versioned SenCore release, command alias, response code	Runtime protocol or device state	Open the command page for the plan's release and inspect the response/event
Device busy	Operation ID and active executor	Concurrent operation	Wait for or cancel the existing operation according to its policy; do not start a second writer
Input required	Input request reference and executor	Protected input flow	Submit the value through the active protected input request; never put it in logs
Time or verification failed	Device facts, clock, final operation event	Runtime verification	Preserve evidence, correct the device/runtime condition, and create a new intent if facts changed
OTA interrupted	Last transfer/apply event and recovery state	Connectivity or recovery path	Follow the declared recovery path; do not flash an arbitrary older image

What to include in a support report

Include the environment, project/device IDs, Board qualified reference, SenCore release, component-definition revision, artifact digest, operation ID, failing step, typed error, and a redacted log excerpt. Exclude API keys, passwords, tokens, certificates, and plaintext secret inputs.

Related reference

• Device Operation Reference
• SenCore Reference
• SenCmd Protocol
• SenCLI Command Reference
• SenCLI troubleshooting