Troubleshooting

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

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 pauses while its earlier invocation is still open, including when it is blocked or failed, 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 Local Worker 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.

An approved action cannot resume

An interrupted run can continue an unused approval for the same task, agent and exact action for seven days when the action does not depend on the old session. For example, a command that obtains a fresh access token and uses it in that same command can continue without another approval.

An old browser target or running process may no longer exist. The agent must check the current state before continuing, and it cannot guess missing action details or run a shortened approval excerpt. If the task stops after repeated recovery failures, use the recovery shown in your Inbox rather than repeatedly approving the same action.

A worker shows as offline

A Worker appears offline when Task Machine on its computer has stopped sending fresh heartbeats. The CLI normally reports every 30 seconds, and Task Machine considers that report stale after 90 seconds. A Worker 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 computer first. It reports the local process, server reachability, and each Workspace's connection 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 Worker 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 Worker and still be unavailable to agents, because detection and agent-availability are two separate things. The Worker 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 computer, 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 it is reporting fresh heartbeats and 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 on the Workers page or on the Worker's page.

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

The CLI says credentials are invalid

Task Machine renews a Worker'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 Worker 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 Worker may start new work. An outdated Worker can still check in, but new agent work waits until the binary is current. Open the Workers tab of the workspace's Workers settings and use the update action when it is offered.

If the page marks the update as manual, update directly on the computer 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 Local Worker does not finish

tama setup opens a browser and waits for you to approve the computer 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 computer 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 unless you set a password in account settings. If you have a password, the sign-in page asks for it after your email, and Email me a magic link instead still sends a link. 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.

You don't recognize a change to your account

Setting or changing your password emails you right away, and so does a sign-in from a browser your account hasn't used before. That email names the browser, an approximate location, and how you signed in. If you did not make the change or sign-in, select Secure your account in that email. It works without signing in, once, within 7 days. After you confirm, Task Machine signs out every browser, removes your password, disconnects every authorized app, and signs out the tama CLI and your Workers. Sign in again with a magic link, then set a new password if you want one, reconnect your apps, and run tama setup on your computers.

If the link expired or was used, sign in with a magic link and select Sign out other browsers in account settings, or change your password, which also signs out your other browsers. Remove apps you don't recognize under Authorized Apps.

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 Worker connects and reports, Workers covers that path end to end. For a problem that is really a permission boundary, the permissions reference maps every action to its key.