Troubleshooting

Common issues and their fixes. If something's not covered here, check the health status (Settings → Site → Health) or contact your administrator.

Sign-In Issues

I can't sign in with my password

• Double-check the email — use the exact address your admin registered you with
• Try the "Forgot password?" link to receive a reset email (requires SMTP configured)
• If SMTP isn't configured, ask your administrator to reset your password manually

The SSO button doesn't work

• Make sure you're clicking the right provider button
• If you see an error after the redirect, your admin's OAuth/LDAP configuration may have changed — contact them
• Clear your browser cookies for both Truetask and the SSO provider, then try again

"Forgot password?" doesn't send an email

• Your workspace probably hasn't configured SMTP yet
• Contact your administrator — they can reset your password directly from Settings → Members

Sync and Connection Issues

I see a "Disconnected" banner

Truetask checks the server connection every 30 seconds. A disconnected banner means your browser lost contact.

• Wait a few seconds — Truetask reconnects automatically when the network comes back
• Reload the page if reconnection doesn't happen
• If the banner persists across reloads, your Truetask instance may be down — contact your administrator

Changes from other users don't appear

• Check for the disconnected banner at the top of the window
• If connected, try a hard reload (Cmd/Ctrl+Shift+R)
• Verify the other user actually saved their changes — draft edits (titles mid-edit, etc.) don't sync until committed

I lost some edits

Truetask only persists changes after they're committed (pressing Enter, clicking away from a field, closing a dialog). Unsaved text in a draft field is not recovered on connection loss.

Permission Issues

I can't see a board someone shared with me

• Ask them to verify you've been added in the board's Share dialog
• Check that the board isn't archived — archived boards are hidden from sidebars
• Sign out and back in to refresh your membership list

A button is greyed out

Your role doesn't allow that action on this board. The most common cases:

• Viewer — you can see everything but can't make changes
• Editor — you can edit tasks but can't manage lists, board settings, members, or automations
• Guest (site role) — you can only access boards you've been explicitly added to

See Boards → Sharing and Roles for the full matrix.

I can't create automations or view the audit log

• Automations require board Admin role
• Audit log requires site Admin or Owner and an Enterprise license
• Ask your site administrator to update your role or verify the license tier

Notification Issues

I'm not getting any notifications

Check each channel:

1. In-app — open the bell icon, make sure nothing is filtered out
2. Browser push — open Profile → Notifications and verify push is toggled on. Check your browser's site permissions for Truetask
3. Email — requires SMTP configured by admin. Check Profile → Notifications for email toggles

See Notifications for setup.

I'm getting too many notifications

Open Profile → Notifications and toggle off categories you don't care about. You can configure in-app, push, and email independently per category.

Push notifications stopped working

• Your browser may have revoked the permission — check browser site settings
• Clearing your browser data removes push subscriptions. Toggle push off and back on to re-subscribe
• Some browsers stop delivering push after extended inactivity — refresh the subscription by toggling it

Performance

The app feels slow

• Check board size — boards with thousands of tasks across dozens of lists can slow down rendering. Archive completed work to reduce the active set.
• Filters help — hiding completed tasks, filtering by current sprint, or grouping by list all reduce the amount rendered
• Close floating frames when you're done with them — multiple open frames add rendering cost
• Hard reload (Cmd/Ctrl+Shift+R) if something seems stuck — this dumps cached state

List view with many tasks loads slowly

• Hide columns you don't need from the columns menu
• Apply a filter to reduce the row count
• Change grouping to None if you're not using groups — grouped views have more overhead

Kanban with very long lists

Kanban uses virtual scrolling automatically — only visible cards render. If it's still slow:

• Reduce the number of details shown per card in Display Preferences → Display
• Hide done tasks from Display Preferences → Behaviour

Import Issues

Import completes but tasks are missing

• Verify you selected the correct done list during import — tasks in a "done" status get marked complete, and "Hide done tasks" may hide them
• Check Display Preferences → Behaviour and disable "Hide done tasks"
• Review the import confirmation — the dialog shows exactly how many lists and tasks were created

Trello attachment import is slow

Trello attachments are downloaded from Trello's servers during import, not the JSON file. Many or large files can take minutes. The dialog stays open throughout.

Members didn't map correctly

• Email addresses must match exactly between the source tool and Truetask
• Members that don't have a Truetask user account are skipped — they don't block the import, but their tasks import without assignees
• Manually re-assign after the fact from the board

Time Tracking

My timer kept running overnight

Truetask automatically stops timers that run longer than 8 hours. The time entry is logged with the actual duration.

To correct the entry:

1. Open the task
2. Go to the Activity tab
3. Click the time entry → edit the duration and notes
4. Save

Timer didn't start

• Make sure you clicked the timer icon on a specific task — the global timer button shows your recent tasks so you can pick one
• Only one timer can run per user at a time — if you have one running elsewhere, the new start stops the old one

File and Attachment Issues

My file won't upload

• Check the file size — large files may be rejected by server limits
• Some file types aren't supported for inline preview but can still be attached
• If S3 storage is configured, connection issues to S3 can manifest as upload failures — contact your admin

Attachment preview doesn't work

Preview supports images, PDFs, videos, and audio. Other file types download when clicked instead of previewing inline.

AI Issues

The AI Assistant button is missing

• Enterprise license required — verify your workspace has it (Settings → Site → License)
• Your administrator needs to configure an AI endpoint in Settings → Integrations → AI
• Check with your admin if both are in place

AI responses are slow or failing

• The AI provider configured in Settings → Integrations → AI may be slow or offline
• Your admin can check the AI endpoint URL and API key, and verify the provider is reachable
• For local AI (Ollama, LM Studio), make sure the model is loaded and the endpoint is running

Still Stuck?

• Health check — Settings → Site → Health tells you if Database, API, or MCP is down
• Contact your administrator — most workspace issues need admin access to fix
• Send feedback to [email protected] with:
  • A description of what you were doing
  • What you expected vs what happened
  • Your browser and OS
  • Screenshots if possible