Skip to content
DocuBot documentation

Troubleshooting guide

Use this guide to diagnose and resolve common issues with repository syncing, GitHub connections, and documentation publishing.

Common issues and symptoms

You can identify most issues by checking the status indicators on your repository cards in the dashboard.

  • Sync status is “Failed”: The documentation generator encountered an error while analyzing your code or building the site.
  • Private repositories are missing: Your GitHub account is not connected, or the connection lacks the necessary permissions.
  • Documentation link returns a 404 error: The documentation site has not finished its initial build, or the URL slug is incorrect.
  • Manual sync button is disabled: You have reached your daily manual sync limit, or a sync job is already in progress.

Fixing repository sync failures

If a sync job fails, DocuBot displays an error message on the repository card. Follow these steps to resolve the failure.

  1. Check the error message: Review the “Last sync error” text on the repository card for specific details about what went wrong.
  2. Verify repository sources: Open the repository settings and ensure all GitHub URLs are correct and point to active repositories.
  3. Check branch names: Ensure the default branch specified in DocuBot matches the primary branch in your GitHub repository (e.g., main or master).
  4. Review ignore patterns: If the sync fails during the “Packaging” phase, your repository might be too large. Add ignore patterns in the advanced settings to exclude large, non-essential directories like third-party libraries or build artifacts.
  5. Retry the sync: Once you update the settings, click Rebuild documentation to start a new sync job.

Resolving GitHub connection problems

DocuBot requires an active GitHub connection to access private repositories and verify repository metadata.

  • Connect your account: If you cannot see your private repositories, go to Settings and click Connect GitHub. Follow the prompts to authorize DocuBot.
  • Refresh the connection: If you recently changed permissions in GitHub, your connection might be stale. Sign out of DocuBot and sign back in, or disconnect and reconnect GitHub in your settings.
  • Verify repository visibility: Ensure the GitHub user who connected the account has at least “Read” access to the repositories you want to document.

Correcting documentation display issues

If your documentation site does not appear as expected or shows incorrect information, check the following configurations.

  • Verify the URL slug: Ensure the slug in your repository settings matches the URL you are trying to visit. Remember that slugs must be unique across the platform.
  • Check the sync status: Documentation only becomes visible once the sync status reaches “Up to date.” If the status is “Queued” or “Syncing,” wait for the process to complete.
  • Review selected document types: If specific pages are missing from your sidebar, verify that those document types are selected in your repository configuration.
  • Update the documentation style: If the tone or structure feels incorrect, try switching to a different General style in the repository settings and trigger a rebuild.

When to contact support

If you encounter an error code not covered in this guide or if a sync failure persists after you follow the steps above, contact our support team for assistance.

When you reach out, please include your repository slug and a description of the symptoms you are seeing.