Troubleshooting

Start with the failure or waiting state shown in Task Machine. Cloud work does not need a Local Worker, so use the machine checks below only when the affected agent runs on your computer. For the commands referenced here, see the CLI command reference. For how machines connect, see worker machines.

Work is waiting without a Local Worker problem

Check the Inbox for a plan approval, question, credential request, exhausted budget, or recoverable Run failure. Resolve the decision there rather than creating a replacement task. A recurring schedule can pause behind its current blocked or failed invocation, so dismissing its notice alone does not resume work.

For a task that has not started, confirm that it is assigned and actionable rather than in Backlog. An unfinished dependency or occupied execution capacity can also hold it. Tasks explains those states, and Budgets and retries distinguishes an operational budget from available paid usage.

If Cloud usage or workspace access is unavailable, follow the displayed billing guidance instead of connecting a computer as a workaround.

If Task Machine says your account is permanently blocked, reconnecting, repeating tama setup, requesting new magic links, or resolving billing will not restore access. Active workspace memberships do not override the block. Contact Task Machine support if you believe it is a mistake.

A machine shows as offline

A machine appears offline when Task Machine on that computer has stopped sending fresh heartbeats. The CLI normally reports every 30 seconds, and Task Machine considers that report stale after 90 seconds. A machine whose local process has quit, lost its network, or been put to sleep will then appear offline.

A persisted offline status also reads as offline regardless of timing.

Run tama status on the machine first. It reports the local process, server reachability, and each Workspace's machine status and last heartbeat. Follow the result:

• Expired credentials: use the exact tama setup command shown to reconnect.
• Stopped process: start it with tama daemon.
• Running but needing recovery: use tama daemon restart to finish active work, restart, and sync.

For background-process errors, inspect ~/.taskmachine/daemon.log.

Once the machine is reporting again, its last-seen timestamp in the workspace's worker settings updates and the status returns to online. If you want it to come back on its own after a reboot, install it as a startup service with tama daemon install-startup.

A worker is detected but agents cannot use it

A coding tool can be present on a machine and still be unavailable to agents, because detection and agent-availability are two separate things. The machine detects whether a tool is installed and reports it. Whether agents may route work to that worker is a workspace setting you control.

A newly detected worker is not automatically open to agents until someone enables it.

Confirm the tool is detected first. tama workers lists every supported tool on the machine, marking each available or missing with the reason. If the local result is right but the workspace still shows an older tool list, run tama sync to make Task Machine on your computer detect and report the complete list immediately.

If the tool shows as available but agents still are not using it, open the workspace's worker settings and enable that worker for agents. A worker is usable by agents only when its machine is reporting fresh heartbeats and the worker is enabled for agent use.

Work still waits after provider access is restored

Task Machine records a waiting period when a local agent tool reaches its provider's usage limit. Restoring quota or changing accounts in that tool does not automatically remove the recorded wait.

Open the usage-limit Inbox item and choose Retry now if you manage the workspace or its agents. Workspace managers can also choose Clear usage blocker in Local workers settings or on the runtime's detail page.

The action requests recovery through the normal work checks. It does not reset provider quota, change accounts, resume a manually paused machine, or enable a disabled runtime. If the provider still refuses work, a new waiting period can appear. See Local workers for the recovery controls and their boundaries.

The CLI says credentials are invalid

Task Machine renews a machine's saved connection automatically, so routine expiry is invisible. When that connection can no longer be restored, the CLI tells you to run tama setup again. Running setup creates a fresh connection unless your account is permanently blocked.

The configuration lives at ~/.taskmachine/config.json, or the legacy ~/.config/taskmachine/config.json for a machine connected by an older release.

If Task Machine support gave you a custom app URL during setup, reconnect with the same --api-url value so the CLI returns to the right workspace connection.

The CLI must be updated

Task Machine can require a minimum tama version before a machine may start new work. An outdated machine can still check in, but new agent work waits until the binary is current. Open the workspace's Local workers settings page and use the update action when it is offered.

If the page marks the update as manual, update directly on the machine and then start Task Machine again:

tama update

If tama status shows that the installed version is newer than the running version, activate the installed binary with tama daemon restart. If the binary is too old to support self-update, reinstall from the Task Machine installer and then restart Task Machine on that computer:

curl -fsSL https://taskmachine.io/install.sh | sh
tama daemon install-startup

irm https://taskmachine.io/install.ps1 | iex
tama daemon install-startup

Connecting a machine does not finish

tama setup opens a browser and waits for you to approve the machine and choose its workspaces. It keeps polling until you approve, deny, or the approval window expires. If the browser does not open automatically, the command prints the URL to open by hand. Finish the approval there and the CLI continues.

An approval that times out reports that it expired and asks you to run tama setup again. A denied approval stops with that result. Setup needs at least one workspace selected, so approve the machine into a workspace rather than approving with none chosen.

A magic-link sign-in does not arrive

Signing in as a person uses a magic link sent to your email. If the link never arrives, first check that the address you entered is correct, look in spam or quarantine, and request a new link.

If several attempts still do not arrive, contact Task Machine support or ask your workspace owner to confirm you were invited with the right address.

If your account is permanently blocked, a new link cannot restore access. Contact Task Machine support if you believe the block is a mistake.

An action you expect is missing

When a button or page you expect is not there, the usual cause is that your role does not carry the permission for it. Task Machine hides actions a role cannot perform instead of showing disabled controls, and a reachable page you lack permission for shows an empty state rather than the controls.

This applies to agents too: an agent's role is the floor on what it may do. Ask a workspace owner or admin to adjust your role, and see the permissions reference for which key gates the action.

From here

If a problem traces back to how a machine connects and reports, worker machines covers that path end to end. For a problem that is really a permission boundary, the permissions reference maps every action to its key.