> ## Documentation Index > Fetch the complete documentation index at: https://specterops-fetch-json-component.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Common issues and solutions when running the GitHound collector. Applies to BloodHound Enterprise and CE This guide covers common issues encountered when running GitHound and how to resolve them. ## Authentication Errors ### "Bad credentials" or 401 Unauthorized * The Personal Access Token (PAT) may have expired or been revoked. Generate a new [Fine-grained PAT](/opengraph/extensions/githound/configure-pat). * Verify the token has all required repository and organization permissions. * Ensure the token is scoped to **All repositories**. ### "Resource not accessible by integration" * Verify you are using an organization administrator account. * Check that the PAT has all required permissions. * For organizations with SAML SSO: [authorize the PAT for SSO access](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) in GitHub settings. ### "Must have admin rights to Repository" * Use a PAT created by an organization owner. * Ensure the PAT has **Administration** read permission on repositories. ## GitHub App Installation Errors ### "Resource not accessible by integration" (App) This error indicates insufficient GitHub App permissions. Verify: * The app has all required permissions listed in [Configure a GitHub App Installation](/opengraph/extensions/githound/configure-app). * The app is installed on your target organization. * The app has access to all repositories (or the specific repositories you need). ### JWT Token Expired GitHub App JWTs expire after 10 minutes. If you encounter authentication errors during a long collection, regenerate the session and resume: ```powershell theme={null} $jwt = New-GitHubJwtSession -OrganizationName "YourOrgName" -ClientId "your-client-id" -PrivateKeyPath "./your-app.pem" -AppId 123456789 Invoke-GitHound -Session $jwt -Resume ``` ### Private Key Issues If you encounter errors related to the private key: * Ensure the `.pem` file path is correct and accessible. * Verify the file contains a complete private key (begins with `-----BEGIN RSA PRIVATE KEY-----`). * If the key doesn't match, regenerate a new private key from the GitHub App settings. ## Rate Limiting ### Symptoms * Collection pauses with messages about waiting for rate limit renewal. * `403 Forbidden` errors with `X-RateLimit-Remaining: 0`. * Very slow collection times. ### Solutions For small to medium environments (\< 500 repos), the built-in rate limit handling automatically pauses and resumes. Allow the collection to complete. For large environments (500+ repos): 1. Use the [App Installation method](/opengraph/extensions/githound/configure-app) for 3x higher rate limits (15,000/hour vs 5,000/hour). 2. Run collection during off-peak hours. 3. Use the [manual step-by-step collection](/opengraph/extensions/githound/collect-data#manual-step-by-step-collection) process for maximum control. ## Crash Recovery ### PowerShell Crashed or Terminal Closed `Invoke-GitHound` writes a per-step output file after each collection function completes. To resume from where you left off: ```powershell theme={null} Invoke-GitHound -Session $session -Resume ``` The `-Resume` flag detects existing per-step files on disk and skips completed steps. Collection resumes from the first incomplete step. **What gets preserved:** * Any step that fully completed has its output file on disk (e.g., `githound_Organization_*.json`, `githound_User_*.json`). * Functions with internal checkpointing (RepositoryRole, Workflow, Secret) save intermediate chunk files, so they can resume mid-function. * `Git-HoundBranch` saves per-page checkpoint files but will re-run from scratch if interrupted mid-function. To start completely fresh and ignore any existing files, run without the `-Resume` flag: ```powershell theme={null} Invoke-GitHound -Session $session ``` ### Corrupt or Truncated Output Files If `ConvertFrom-Json` errors occur or resume skips a step with incomplete data, delete the corrupt per-step file and re-run with `-Resume`: ```powershell theme={null} Remove-Item ./githound_Repository_*.json Invoke-GitHound -Session $session -Resume ``` ## Collection Errors ### "Cannot index into a null array" A collection function returned no data, likely due to a network interruption or permission issue. Run the specific function individually to diagnose: ```powershell theme={null} $org = Git-HoundOrganization -Session $session $org # Check if data was returned ``` ### Empty or Partial Collection * Verify all required PAT permissions are configured. * Use the step-by-step collection process to identify which function is failing. * Check that GitHub Actions is enabled for the organization if workflow/environment data is missing. ## Large Environment Issues ### Collection Takes Too Long For organizations with thousands of repositories, a full collection can take several hours. 1. Use the [App Installation method](/opengraph/extensions/githound/configure-app) for higher rate limits. 2. Run collection during off-peak hours. 3. Use `-Resume` to pick up where you left off if collection is interrupted. ### Memory Issues * Use a 64-bit PowerShell session. * Close unnecessary applications to free memory. * Use the step-by-step collection process to collect in smaller batches. ## Missing Data ### No Workflow or Environment Nodes * Verify GitHub Actions is enabled in your organization settings. * Check that the PAT has **Actions** read permission on repositories. * Repositories with Actions disabled are intentionally skipped. ### No External Identity Nodes (SAML/SSO) * SAML SSO must be configured for the organization. * The PAT user must be an organization owner. * A GitHub Enterprise license is required for SAML identity data. ## BloodHound Import Issues ### "Invalid JSON" Error Validate the JSON file before uploading: ```powershell theme={null} Get-Content ./githound_*.json | ConvertFrom-Json ``` If validation fails, re-run the collection or use `-Resume` to regenerate the affected step. ### Nodes or Edges Not Appearing * Ensure you are using a BloodHound version that supports OpenGraph extensions. * Check BloodHound logs for import errors. * Verify the JSON structure matches the expected format. ## Getting Help If you encounter issues not covered here: 1. Check [GitHub Issues](https://github.com/SpecterOps/GitHound/issues) for known problems. 2. Open a new issue with your PowerShell version (`$PSVersionTable`), GitHound version, full error message, and approximate environment size. 3. Join the `#githound` channel on the [BloodHound Community Slack](https://slack.specterops.io/).