Troubleshooting

When something goes wrong on hosted NFLTR at nfltr.xyz, use dashboard and CLI symptoms below—not internal service layout.

Worker offline

$ nfltr worker --labels nfltr.supports_task_mode.implement=true,nfltr.worker.tool=run_task,pool=dev \
    --mcp-command "nfltr claude-mcp --cwd ~/project --task-mode \${TASK_MODE}"

$ nfltr orch fleet workers --json

Task queued

$ nfltr orch task status --task task-stuck-queued --events 10

rate_limit

You see: rate_limit / rate_limited, HTTP 429, or drawer countdown rate_limit_retry_at. Try: wait for reset; reduce parallel fan-out; retry with a smaller objective.

$ nfltr orch task watch --task task-rate-limited

binding_lost

You see: failed with binding_lost after heartbeat loss. Try: restart worker on the host or dispatch to another ready machine with the same labels.

$ nfltr orch task status --task task-binding-lost --events 15

transport_drop

You see: stalled progress, reconnect banners, retryable=true. Try: wait for reconnect; cancel and redispatch narrowly if needed.

$ nfltr orch task result --task task-transport-drop

Verification failed

$ nfltr orch start task --worker MacBook-pro.review-1 --task-mode review --objective "Re-review after rework" --watch

Copy task id, worker id, and last summary for support.

Practical tips

NFLTR persists task history on the hosted control plane at nfltr.xyz, so reconnecting planners and dashboard viewers see the same timeline. Share runs with teammates using task ids and dashboard deep links instead of pasting full JSON envelopes. For production-impacting objectives, configure approval gates so a human confirms in the Atlas attention rail / task drawer before work continues. Combine the CLI examples above with the Causal Operations Atlas (causal canvas, Trace Lab) when you need mobile monitoring or inner-LLM turn detail documented in the observe orchestration guide.