Known Issues

Purpose

Record only currently reproducible, code-verifiable known issues.

Current Status

No known issues are documented on this page at this time.

Reason for the minimal page:

  • the old reference snapshot contained issues that are not fully verifiable from the current apps/node/src/ surface alone
  • this docs refactor documents only issues we can verify against current implementation

This is an intentional state, not a placeholder contract. We do not currently maintain a code-backed known-issues catalog in the Node API or CLI. Use doctor, version --check-compat, and command-specific error codes instead.

Verification Boundary

What this page does mean:

  • there is no currently maintained, code-backed list of known issues in apps/node/src/
  • common operational failures are documented under exact error-code pages such as Operator App and Version Compatibility
  • agents should use live checks like doctor, version --check-compat, and command-specific error payloads instead of assuming a hidden issue catalog exists

What this page does not mean:

  • that the project has zero bugs
  • that every operational failure has a dedicated known-issues entry
  • that an issue was fixed just because it is absent from this page

Practical Verification Pattern

When you suspect a current issue, verify it with a reproducible command and its exact JSON output:

clawperator doctor --device <device_serial> --operator-package <package>
clawperator version --check-compat --device <device_serial> --operator-package <package>
clawperator snapshot --device <device_serial> --operator-package <package>

Use those outputs to decide where the issue belongs:

  • installation, permissions, handshake, or crash recovery: Operator App
  • CLI and APK version mismatch: Version Compatibility
  • public API or CLI contract regression: the matching page under docs/api/

Where To Track New Issues

  • GitHub issues for project-level bugs and regressions: https://github.com/clawperator/clawperator/issues
  • Operator App for operational recovery guidance
  • Version Compatibility for CLI and APK mismatch problems

If a current issue becomes reproducible and code-verifiable, add it here with:

  • exact trigger
  • affected surface
  • exact command or request used to reproduce it
  • exact error code or failing check id
  • one concrete verification pattern after the workaround
  • workaround
  • recovery or follow-up path

Diagnostic Tools

When investigating issues:

  1. Check versions first - Many issues are version mismatches: bash clawperator version clawperator version --check-compat --device <device_serial> --operator-package <package>

  2. Run doctor for a comprehensive health check: bash clawperator doctor --device <device_serial> --operator-package <package>

  3. Stream logs to see what is happening in real time: bash clawperator logs

  4. Check the log file directly: bash cat ~/.clawperator/logs/clawperator-$(date +%F).log

See Logging for log format details and Version Compatibility for compatibility rules.