Embodied troubleshooting

A machine that escalates when it should not, or acts when it should not, almost always comes down to memory, mode, rules, or license. Start with neuraframe status and the decision log.

The robot escalates everything

Three usual causes. The device may be unlicensed, so it is in pass-through and serves nothing from memory; run neuraframe status. The memory pack may not have imported, so the store is empty; re-import it and confirm the path. Or the mode may be SHADOW, which never actuates by design; move it to ASSIST when you are ready.

neuraframe status
MemoryPack.import_("walker.nfmem", store_dir)
agent.set_mode(Mode.ASSIST)

The memory pack will not import

Check that the file copied completely and that the store directory is writable by the service user. A pack exported from a much newer build may need a matching engine version; keep the training host and the device on the same Embodied line.

A rule vetoes actions it should not

Read the decision log: every veto records which rule fired. If a LAW is too strict for the situation, adjust the rule definition in your integration; remember a numeric limit can be strengthened in the field but not loosened, so to relax a limit you change it at the source and redeploy, on purpose.

Behavior changed after adding a sensor

Declaring a capability augments memory and flags only the decisions the new sensor changes for review; it does not discard what was learned. Call needs_review() to see exactly which decisions were re-examined, and confirm those are the ones you expected. Removing a sensor is non-destructive and should not change validated behavior.

agent.capabilities.needs_review()   # the decisions to re-check, and nothing else

An escalation does not reach a safe state

The agent stops and calls your hook; what happens next is your hardware and your code. If a robot does not come to a genuinely safe state on escalation, the fix is in your escalation handler and your independent safeguards (emergency stop, motion limits), not in NeuraFrame. This is the operator's responsibility; see Operating & modes and the EULA.

License will not activate

Confirm the subscription is active and the device fingerprint matches. For an offline robot, use offline activation: send the fingerprint and install the signed license file. For a fleet, draw a seat from your pool rather than activating by hand.

Still stuck

Collect neuraframe doctor output, recent neuraframe logs, and the relevant decision log entries, then reach us from the contact page.