Troubleshooting

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 fundamental steps that resolve approximately 80% 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 that prevent Zenhub from functioning properly. 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 like Zenhub.

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

Resolving "Workspace Cannot Be Loaded" Errors

This 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 in a workspace, 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. This resolves data conflicts that prevent workspace loading when simple cache clearing isn't sufficient.

Finally, try different access methods. If you're using the browser extension, try accessing through app.zenhub.com instead, or vice versa. Different access methods sometimes work when others fail due to specific browser or extension issues.

Fixing Drag-and-Drop Functionality Problems

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

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 between pipelines. 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 functionality. 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. These errors often indicate specific problems that prevent functionality. Screenshot any errors you find and include them when contacting support.

If these checks don't reveal the issue, try refreshing the workspace completely by navigating away and back. Sometimes drag-and-drop functionality requires a fresh workspace load to restore proper operation.

Addressing Real-Time Update Issues

When changes don't appear immediately or team members don't see updates you've made, 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 the repository settings under "Webhooks" and verify that recent deliveries have succeeded.

Manual refresh test: If real-time updates aren't working, 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 or network restrictions can block webhook deliveries. Check with your IT team if webhook deliveries consistently fail in your organization, as they may need to whitelist Zenhub's webhook endpoints.

Troubleshooting Browser Extension Problems

Extension-specific issues require different approaches than web app problems.

Force extension updates by visiting your browser's extension management page. Browser extensions don't always auto-update promptly, so manually check for updates and force them when available.

For persistent problems, perform a complete reinstall. Remove the Zenhub extension entirely, restart your browser, then reinstall from the official browser extension store. This resolves many extension problems that updates alone won't fix.

Check that the Zenhub 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 conflict with Zenhub. Temporarily disable other extensions to identify conflicts, especially those that modify GitHub's interface or handle mouse interactions.

Resolving GitHub Integration Issues

Problems with GitHub connectivity affect many Zenhub functions and require specific troubleshooting steps.

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, resolving most integration issues.

Organization membership: Being a repository collaborator provides different access than organization membership. Some Zenhub features require full organization membership rather than just repository access. Ask your GitHub organization administrator to add you as a member if needed.

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.

Repository visibility: Private repository access requires explicit permissions, while public repositories may have different access rules. Confirm that repository visibility settings align with your expected access level.

Special Case: Invalid Tokens Error

If you encounter an "Invalid Tokens" error, follow this specific resolution process:

1. Log out of Zenhub by visiting https://app.zenhub.com/logout

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

3. Log out of GitHub

4. Clear browser cache and cookies

5. Close and reopen your browser completely

6. Log back into GitHub

7. Log back into Zenhub using "Continue with GitHub"

Getting Help from Support

Before gathering detailed troubleshooting information, check if there's a known service issue affecting Zenhub or GitHub.

Check service status first:

• Zenhub Status: https://status.zenhub.com/

• GitHub Status: https://www.githubstatus.com/

Since Zenhub integrates deeply with GitHub, problems on the GitHub side can affect Zenhub functionality. Checking both status pages helps you determine whether the issue is service-wide or specific to your setup.

When basic troubleshooting doesn't resolve your issues and status pages show no incidents, providing the right information helps support diagnose and resolve problems faster. You don't need to gather everything listed below before reaching out, but the more context you can provide, the quicker support can investigate and respond.

Essential information that speeds up resolution:

1. Account and environment details:

• GitHub username

• Zenhub email address

• Zenhub organization name

• Access method: Web app (app.zenhub.com) and/or browser extension

• Browser: Firefox or Chrome (include version number)

2. Issue context:

• Steps to reproduce the problem

• Screenshots or screen recordings showing the issue

• Specific error messages (exact text or screenshots)

• Whether this affects just you or multiple team members

3. Technical details (if available):

• Browser console errors (F12 → Console tab)

• Network tab information showing failed requests

• Recent changes to your setup or permissions

How to gather console information:

If support requests console information, open your browser's developer tools by pressing F12. Navigate to the Console tab and reproduce the issue. Take a screenshot of any red error messages that appear. The Network tab can also show failed requests if support needs to investigate connection issues.

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 or social media for service announcements.

Q: Why can I see issues but can't move them between pipelines?
A: This typically indicates 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.