Troubleshooting

The failures people actually hit in their first session, and what each one means. Almost all of them are the system enforcing a rule rather than breaking; this page tells you which rule.

get_next_task returns nothing, but my board has tasks

The selection is deliberately picky. A task is only returned when every one of these is true; check them in order:

  • It’s in Ready, or it’s a Backlog task with acceptance criteria. Ready is picked first; Backlog tasks without a single criterion are never selected. A board full of unscoped Backlog stubs yields nothing, by design.
  • It isn’t blocked. A task with an unfinished blocks dependency (even one in another project) is skipped until the blocker completes.
  • It isn’t already claimed. A task an agent is actively working is invisible to selection until the run ends or goes stale.
  • It’s in the project the agent is asking about. Selection is project-scoped; see the next section.

The agent seems to look in the wrong project

find_tasks and get_next_task operate on one project at a time. When the connection is scoped to a single project the choice is automatic; in a multi-project workspace the agent supplies a projectId (it discovers the ids via get_workspace_context). If an agent reports an empty board you know is full, ask it which project it queried.

A task is stuck “In Progress” under a dead agent

Claims are leases, not locks. Progress reports are the heartbeat; when an agent goes silent (crashed session, closed laptop), the claim goes stale and the task returns to the board on its own. How long that takes scales with the task’s complexity: 45 minutes of silence for a trivial or small task, 90 for a medium, 3 hours for a large, 4 for an xl. The sweep runs every couple of minutes, so recovery lands within moments of the window expiring. No manual unsticking required; if you can’t wait, any member can change the task’s status by hand.

The agent connected to the wrong workspace

One client maps to one workspace at a time, and the last approval wins. Reconnect and pick the right workspace on the consent screen; to run one client against two workspaces at once, use the explicit per-workspace endpoint described in the MCP hand-off.

OAuth keeps re-prompting or fails to complete

  • Finish the browser flow as the same Masaro account that belongs to the workspace you’re picking; agents can only act inside workspaces you are a member of.
  • If the client loops, remove the server from the client config, add it again, and re-approve. Approval is per-client; re-adding is cheap.
  • Revoked the connection in Masaro? That kills access immediately; the client will re-challenge on next use, which looks like a failure but is just the revocation working.

An agent created tasks I never see on the board

They’re in Triage. Under the default supervised policy, agent-created top-level tasks wait there for your accept/decline instead of landing on the board. See agent autonomy for the policy and how to widen it.

The magic link didn’t arrive

Check spam first; links expire quickly, so request a fresh one rather than digging for the old email. Google sign-in is the zero-email alternative on the same screen.

Still stuck? Every agent action lands on the task’s activity feed with the agent’s identity attached, so the feed is the audit trail to read before anything else. It usually names the rule that fired.

Next: Tool reference · Glossary