Documentation › User Guides › Device Owners › Stage 3 › Troubleshoot

Device Owner mode launches Q3 2026. The screens and flows described below are based on the implementation under active development. We'll update these chapters with final screenshots and verified click-paths at launch.

Troubleshoot common issues

Four symptoms cover ~90% of device-owner support tickets. Each has a short diagnostic path. Walk top-to-bottom.

Symptom 1 — Device shows "offline"

The agent sends a heartbeat every few seconds. Three missed heartbeats and the coordinator flips the device to offline. Walk the chain:

  1. Agent process running?
    • Windows: Task Manager → Services → Zyra Agent. State should be Running.
    • macOS: launchctl list | grep zyra
    • Linux: systemctl status zyra-agent
  2. Network reachable? The agent dials an outbound TLS websocket. From the same machine: curl -I https://app.getzyra.io — expect HTTP 200.
  3. Recent system update? Some Windows feature updates disable startup services. Re-enable in services.msc.
  4. Restart the agent. Stop-and-start beats most transient failures.

If still offline, the agent log is the next step:

  • Windows: %PROGRAMDATA%\Zyra\logs\agent.log
  • macOS: ~/Library/Logs/Zyra/agent.log
  • Linux: journalctl -u zyra-agent -n 200

Symptom 2 — Capability score lower than you expect

The score is calculated from hardware_specs collected at register and refreshed on each heartbeat. Two common causes:

  • Hardware detection misread. Check Devices → [device] → Hardware specs. CPU cores wrong? Re-run the agent's self-check: zyra-agent --recapture [VERIFY: CLI flag name at GA].
  • Caps lowered too far. The score reflects what you've made available, not raw hardware. Bumping CPU cap from 25% → 75% on a 16-core machine roughly triples the CPU contribution.

The math is in backend/app/models/device/methods.py: desktop = up to 300 CPU + 300 RAM + 400 GPU; Android = up to 400 CPU + 600 RAM.

Symptom 3 — Online but no jobs landing

Three reasons, ordered most → least common:

  1. Marketplace demand is genuinely low right now. The platform doesn't manufacture jobs — see chapter 2.
  2. Capability score too low for available jobs. Jobs declare a minimum score; if yours sits below it, you don't match. Raise caps, opt into GPU, or wait for lighter jobs.
  3. Availability conflict. A scheduled window may have just closed. Check Devices → [device] → Schedule.

Logs: Devices → [device] → Activity shows recent match attempts and why they didn't land (reason: capability_below_threshold, reason: outside_schedule, etc.).

Symptom 4 — Tasks fail

Tasks land but error out. Click the failed task in Activity for the error class:

  • docker_unavailable — Docker Desktop stopped (Windows/macOS) or the docker daemon isn't running (Linux). Restart Docker.
  • disk_full — The sandbox working directory ran out of room. Free space; lower disk allocation in capabilities; consider a larger disk cap if you have headroom.
  • oom_killed — Task tried to use more RAM than your cap permits. Raise the RAM cap if you have spare.
  • timeout — Task exceeded its own max-runtime. No fault of yours — earnings still post for time actually used.
  • sandbox_setup_failed — Rare. Usually antivirus blocking container creation. Add the agent's working directory to the AV exclusion list.

Still stuck

Email support@getzyra.io [VERIFY: support email at GA] with:

  1. Your device ID (top of the device detail page).
  2. The timestamp of the issue (UTC).
  3. The last ~200 lines of the agent log.

Most replies inside one business day.

What's next

← 2. Maximize your earnings | 4. Monitor device health →

Last reviewed: 2026-05-21