Appearance
Troubleshooting
Symptom, cause, fix. Each entry links to the page with the full explanation.
Signing in and email
The password reset email never arrives
The login page tells you when this is the server and not you. Reset emails aren't going out means the workspace cannot send mail at all, so reset links and one-time sign-in codes will not arrive. Ask an admin to reset your password directly.
Self-hosted only
Mail needs an SMTP server configured in Settings > Server > SMTP. Until it is, password resets, sign-in codes, invitations and digests all go nowhere. See SMTP.
If the login page does not show that notice, the mail was sent. Check the spam folder before asking for another.
A reset link says it is invalid or expired
Reset links are single use and time limited. Request a new one from Forgot your password? on the login page.
Sign-in says the account is disabled
An admin turned the account off. Only they can turn it back on, from Settings > Members & Teams > User Directory.
Truetask asks for a new password right after signing in
An admin set a temporary password for you. Enter that temporary password as the current one and choose your own to continue.
Boards and views
A board opens on a dialog that says "Set your In Progress list"
Every board needs at least one list in the In Progress lane, and this board has none. The dialog cannot be dismissed until you pick an existing list or create one. Only board admins see it; everyone else can keep working. See Board flow.
A view tab is missing
Four different things hide a tab, in this order:
- A board admin removed it from the board's shared tab set.
- You hid it for yourself in the view preferences, which follows you across devices.
- You turned its feature off in the Features dialog.
- The board is a database, whose tabs are fixed to List, Forms and Automations and cannot be widened.
Check your own override first: open the views menu in the tab strip and turn the tab back on for You. See Board views and Customize.
The Automations tab is missing
Automations is the one board view that only board admins get. If you are an editor or a viewer on that board, the tab does not exist for you. Ask a board admin, or someone with the workspace Owner or Admin role, who is always a board admin. See Roles and permissions.
The Code tab on a task or the Reviews page is gone
The Code & reviews feature is off in your Features dialog. That toggle hides the Reviews view in the sidebar and the Code tab on tasks. It deliberately leaves the board's own Code view alone, so the board tab stays.
A view will not stay as the board's default
Code and Automations can never be a board's default view. Code would open a repo-less board onto the git setup screen, and Automations does not exist for non-admins. Both remain perfectly valid visible tabs.
Plans and licensing
A setting shows a crown icon
Truetask Cloud only
The crown marks a pane your current plan does not include. See Plans and billing.
Self-hosted only
Self-hosted instances have no plan gating. A gated pane there means the instance is running with no active license, or on a license tier below the feature. See License.
Automations were disabled after a plan change
A plan with a lower automation limit disables the extra ones rather than deleting them. A toast says how many. Re-enable the ones you want, up to the new limit, in Settings > General > Automations.
A license banner appears, or the app redirects to Activate
Self-hosted only
An instance with no license key gets a 3-day grace period. During it you see a banner counting the days down and everything keeps working. When the grace period ends, every page redirects to the Activate license screen until a key is entered. Enter it there or in Settings > Site > License. See License.
Agents and MCP
An MCP client cannot connect
Work through these in order.
| Check | What to look for |
|---|---|
| The URL | Streamable HTTP is <your workspace>/mcp. SSE is <your workspace>/mcp/sse. They are not interchangeable. |
| The header | The token goes in Authorization: Bearer <token>, not in the URL. |
| The token | Tokens can be given an expiry date. An expired one fails every call. Create a new one and paste it in again. |
| The scope | A Read only token cannot create or change anything. Pick Read & write if the tool needs to write. |
| The client | ChatGPT custom connectors authenticate with OAuth, which Truetask's MCP server does not accept yet. |
Demo workspaces refuse MCP token creation entirely.
See MCP and API tokens.
An agent run shows Stalled
A watchdog flags a run when there has been no agent activity for more than 30 minutes. Activity means a heartbeat, a step update or a run log entry, so a long quiet stretch of thinking counts as silence.
Any real activity clears the flag by itself. If the agent is genuinely gone, retry the current step, reassign the run or cancel it from the run's own controls. See Agent activity.
A kickoff expired
Nothing picked the kickoff up before its deadline, which is 24 hours unless the caller set a shorter one. Two usual causes:
- The agent has no power that could take the work. Check External access, Local access and Auto-start on the agent's profile.
- The runner behind Auto-start never answered. The agent's profile shows the last call and whether it connected; a rejected signature means the runner has a different secret.
See Delegating work and Runners.
A coding tool launch falls back to "Copy agent prompt"
The split button falls back to the copy action when it cannot offer the tool you picked. The usual reasons:
- The repository has no usable remote URL, or the remote carries credentials and Truetask refuses to hand it to a tool. That takes Open in VS Code and Copy checkout out.
- The generated prompt is too long for a link, which takes Open in Cursor out.
- You are in the browser rather than the desktop app, so a command-line tool such as Claude Code, Codex CLI or Zed can only be handed to you as a command.
Paste the copied prompt into the tool, or install the desktop app so Truetask can launch the tool natively. See Coding tools.
Git
A repository is linked but the webhook is not registered
The Git pane says Linked, but the webhook could not be registered or Webhook not registered next to the repository. It nearly always means the token lacks the scope that lets Truetask create a webhook:
- GitHub: a classic token needs
repoplusadmin:repo_hook, or a fine-grained token needs read/write on Contents, Pull requests, Issues and Webhooks. - GitLab: a token with the
apiscope, on an account with the Maintainer role on the project. - Gitea: a token with read and write on Repository and Issue.
The other cause is reachability: the provider has to be able to call your workspace, so a private instance with no public URL cannot receive one. Fix the token or the URL, then re-link the repository from the board's Code view settings. See Connecting a repository.
Notifications
Push notifications never arrive
| Cause | Fix |
|---|---|
| The browser blocked them | The profile's notification settings say Notifications are blocked by your browser. Allow them in the browser's site settings. |
| The push service is blocked | You see a message about the browser blocking the push service. Enable push messaging in the browser settings and restart it. Privacy-hardened browsers often disable it by default. |
| The server has no keys | You see Push notifications are not configured on this server. |
Self-hosted only
Web push needs a VAPID key pair in the instance's environment. The install script generates them; an instance upgraded from an older setup may not have them. See Install.
See Notifications.
Files and uploads
An upload is rejected
The workspace has a per-file size limit, set in Settings > General > Uploads. It defaults to 25 MB and can go up to 500 MB. Avatars, task covers and the workspace logo ignore that setting and use a fixed 10 MB limit.
Truetask Cloud only
Your plan also sets its own per-file cap and a total storage cap for the workspace. A rejected upload names the limit it hit, and the app warns you as the storage fills. See Plans and billing.
Backups
The backup list is empty
Self-hosted only
Automatic backups only run when a cron expression is set. Open Settings > Server > Backups, set the Cron Expression field, and save; leaving it empty disables automatic backups entirely. Create Backup on the same pane makes one immediately, which is the quickest way to tell whether the backup itself works.
If backups are stored on S3, an unreachable bucket fails the write. Re-check the bucket, region, endpoint and keys in Settings > Server > S3 Storage. See Backups and S3 storage.
The network policy
Link previews, Unsplash or an agent's web read do nothing
Self-hosted only
Truetask is offline-first, and nothing reaches the internet until you allow it. Turn on Allow features that reach the internet in Settings > General > Network. That one switch covers link previews for covers, Unsplash, and the pages agents read.
A second switch, Allow private network targets, lets automations, webhooks and agent fetches reach addresses on your own network such as 10.x, 192.168.x and .internal. It is off by default, so a webhook pointed at an internal host is refused until you turn it on. See Network policy.
Errors
An error mentions ERR-xxxxxx
That is an error reference. Take it to Settings > Server > Logs and search for it: the matching entry has the level, the source, the request id, the user and the full message. The same pane filters by level, source and date, which is usually enough to see whether it was a one-off.