How do I troubleshoot common Zenhub issues and errors?

When Zenhub isn't working as expected, most issues can be resolved with systematic troubleshooting steps. Common problems include workspace loading errors, permission issues, drag-and-drop problems, and browser extension conflicts.

Starting with basic troubleshooting

Before diving into specific error messages, try these fundamental troubleshooting steps that resolve the majority of Zenhub issues.

Clear your browser cache and cookies for both Zenhub and GitHub, then restart your browser completely. Browser data conflicts often cause loading problems and display issues that prevent Zenhub from functioning properly.

Update your Zenhub browser extension by visiting your browser's extension management page. Outdated extensions frequently cause functionality problems, so force an update or reinstall the extension entirely if automatic updates haven't occurred recently.

Check your GitHub permissions to ensure 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.

Try accessing Zenhub in a different browser or incognito mode. This helps identify whether the issue is browser-specific or related to your browser settings, extensions, or stored data.

Resolving "Workspace cannot be loaded" errors

This common error message 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 checking your GitHub repository access to verify that you have read access to at least one repository in the workspace. If you've lost access to all repositories in a workspace, you won't be able to load it until permissions are restored.

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

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.

Try accessing the workspace through different 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 or drag-and-drop stops working, this typically indicates permission or browser-related issues.

First, confirm you have write permissions for the underlying GitHub repository. Drag-and-drop requires write or push permissions, while read-only access allows you to view issues but not move them between pipelines.

Test the functionality with different issue types by trying to move both GitHub issues and Zenhub issues. This helps identify whether the problem affects all issue types or just specific ones, which indicates whether the issue is permission-related or broader functionality problems.

Disable other browser extensions temporarily, particularly productivity tools or mouse gesture extensions that can interfere with drag-and-drop functionality. Other extensions sometimes conflict with Zenhub's interface interactions.

Check for JavaScript errors by opening your browser's developer console (F12) and looking for red error messages when attempting to drag and drop. These errors often indicate specific problems that prevent functionality.

Try refreshing the workspace completely. Sometimes drag-and-drop functionality requires a fresh workspace load, so navigate away from the workspace and back to reset the interface.

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.

Verify 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."

Check for webhook delivery failures: In GitHub's webhook settings, review recent deliveries to see if any have failed. Failed webhook deliveries prevent Zenhub from receiving updates about issue changes.

Test with manual refresh: 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 broader synchronization problems.

Review network connectivity: Corporate firewalls or network restrictions can block webhook deliveries. Check with your IT team if webhook deliveries consistently fail in your organization.

Troubleshooting browser extension problems

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

Force extension updates: Browser extensions don't always auto-update promptly. Manually check for updates in your browser's extension management page and force updates when available.

Reinstall the extension: Complete removal and reinstallation resolves many extension problems. Remove the Zenhub extension entirely, restart your browser, then reinstall from the official browser extension store.

Check extension permissions: Ensure the Zenhub extension has all necessary permissions for both GitHub and Zenhub domains. Extension permission changes sometimes occur during browser updates.

Review conflicting extensions: 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.

Clear extension data: Some browsers allow clearing extension-specific data without affecting other browser data. This targeted approach can resolve extension problems without broader browser impact.

Resolving GitHub integration issues

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

Re-authenticate with GitHub: 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.

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

Review 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.

Verify 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.

Getting additional help

When basic troubleshooting doesn't resolve your issues, gather specific information to help support diagnose problems more effectively.

Document error messages: Take screenshots of specific error messages, including any browser console errors. Exact error text helps support identify issues more quickly than general problem descriptions.

Note browser and extension versions: Include your browser version, Zenhub extension version, and operating system when reporting issues. Version compatibility sometimes causes specific problems.

Test across different environments: Try accessing Zenhub from different browsers, devices, or network connections to help isolate whether issues are environment-specific or account-related.

Gather console information: If requested by support, open your browser's developer tools (F12) and capture console and network tab information while reproducing the issue. This technical data often reveals the root cause of complex problems.

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/private mode to rule out extension conflicts, then check GitHub permissions, verify 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.