Troubleshooting

Diagnose and fix the most common Zenhub issues, from browser conflicts and permissions to GitHub integration problems.

When Zenhub isn't working as expected, most issues stem from browser data conflicts, permission settings, or GitHub integration problems. This guide helps you diagnose and resolve common issues systematically.

Quick diagnostic reference

Starting with basic troubleshooting

Before investigating specific error messages, try these steps — they resolve the majority of Zenhub issues.

Clear browser data completely
Remove cache and cookies for both Zenhub and GitHub, then restart your browser. Browser data conflicts often cause loading problems and display issues. For persistent issues, clear local storage and session storage using your browser's developer tools.

Update your Zenhub browser extension
Visit your browser's extension management page and force an update or reinstall the extension entirely. Outdated extensions frequently cause functionality problems, especially after browser updates.

Verify GitHub permissions
Check that you have appropriate access to the repositories in your workspace. Many Zenhub issues stem from insufficient GitHub repository permissions or organizational settings that block third-party applications.

Test in a different environment
Access Zenhub in incognito mode or a different browser. This helps identify whether the issue is browser-specific or related to your account configuration.

Workspace loading errors

The "Workspace cannot be loaded" error appears when Zenhub cannot access or display your workspace content. The issue usually relates to permissions or browser problems rather than Zenhub server issues.

Start by verifying your GitHub repository access — you need read access to at least one repository in the workspace to load it. If you've lost access to all repositories, contact your GitHub administrator to restore permissions.

Next, confirm your GitHub organization approves third-party applications. Organization owners need to approve Zenhub access through GitHub's organization settings under third-party application access if your organization restricts external applications.

If permissions are correct, clear your browser storage completely including local storage and session storage for both Zenhub and GitHub domains. Finally, try different access methods — if you're using the browser extension, try app.zenhub.com instead, or vice versa.

Drag-and-drop problems

When you can't move issues between pipelines, this typically indicates a permission or browser-related issue.

Permission requirements
Drag-and-drop requires write or push permissions for the underlying GitHub repository. Read-only access allows you to view issues but not move them. Contact your repository administrator to request write access if needed.

Testing for issue type
Try moving both GitHub issues and Zenhub issues. If both fail, you're experiencing a browser or extension problem. If only GitHub issues fail to move, this confirms a permission issue.

Extension conflicts
Disable other browser extensions temporarily, particularly productivity tools or mouse gesture extensions that can interfere with drag-and-drop. Re-enable extensions one by one to identify conflicts.

JavaScript errors
Open your browser's developer console (F12) and look for red error messages when attempting to drag and drop. Screenshot any errors and include them when contacting support.

Real-time update issues

When changes don't appear immediately or teammates don't see your updates, webhook and synchronization issues are likely causes.

Webhook configuration
Zenhub relies on GitHub webhooks to receive real-time updates. Repository administrators should check that Zenhub webhooks are properly configured in repository settings under Webhooks and verify that recent deliveries have succeeded.

Manual refresh test
Manually refresh the workspace to see if changes appear. This confirms whether the issue is webhook-related or indicates broader synchronization problems.

Network restrictions
Corporate firewalls can block webhook deliveries. Check with your IT team if webhook deliveries consistently fail, as they may need to whitelist Zenhub's webhook endpoints.

Browser extension issues

Force extension updates by visiting your browser's extension management page — extensions don't always auto-update promptly. For persistent problems, remove the Zenhub extension entirely, restart your browser, then reinstall from the official browser extension store.

Check that the extension has all necessary permissions for both GitHub and Zenhub domains. Extension permission changes sometimes occur during browser updates, requiring you to re-grant permissions. Other GitHub-related extensions or productivity tools can also conflict with Zenhub — disable other extensions temporarily to identify the cause.

GitHub integration issues

Complete re-authentication
Sign out of both Zenhub and GitHub, clear browser data, then sign back into GitHub first, followed by Zenhub. This refreshes authentication tokens and permissions.

Organization membership
Being a repository collaborator provides different access than organization membership. Some Zenhub features require full organization membership rather than just repository access.

SAML authentication
Organizations using SAML single sign-on require periodic re-authentication. If your organization uses SAML, ensure your authentication is current for both GitHub and Zenhub.

Resolving invalid tokens errors

If you encounter an "Invalid Tokens" error, follow these steps in order:

1. Log out of Zenhub at app.zenhub.com/logout

2. Revoke Zenhub application permissions in GitHub at github.com/settings/applications

3. Log out of GitHub

4. Clear browser cache and cookies

5. Close and reopen your browser

6. Log back into GitHub

7. Log back into Zenhub using Continue with GitHub

Getting help from support

Before reaching out, check whether there's a known service issue affecting Zenhub or GitHub.

• Zenhub status: status.zenhub.com

• GitHub status: githubstatus.com

When contacting support, include your GitHub username, Zenhub email address, organization name, browser and version, steps to reproduce the issue, screenshots or screen recordings, and any console errors from your browser's developer tools (F12 → Console tab).

FAQ

Q: Why does Zenhub work in one browser but not another?
A: Different browsers handle extensions, cookies, and JavaScript differently. Try clearing browser data, updating the browser, and ensuring the Zenhub extension is properly installed and updated in the problematic browser.

Q: What should I do if clearing cache and cookies doesn't help?
A: Try accessing Zenhub in incognito mode to rule out extension conflicts, verify GitHub permissions, confirm organization third-party app approval, and test with a different browser entirely.

Q: How can I tell if an issue is on my end or a Zenhub service problem?
A: Check if other team members experience the same issue, try accessing Zenhub from different devices or networks, and visit Zenhub's status page for service announcements.

Q: Why can I see issues but can't move them between pipelines?
A: This typically means you have read permissions but lack write permissions for the GitHub repository. Contact your repository administrator to request write access.

Q: What information should I include when contacting Zenhub support?
A: Include specific error messages, screenshots, your browser and extension versions, steps to reproduce the issue, and any console errors from your browser's developer tools.

Q: How long should I wait before assuming an issue isn't temporary?
A: Most temporary issues resolve within 5–10 minutes. If problems persist longer than 15 minutes and basic troubleshooting doesn't help, contact support.