Skip to main content
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.
  • 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 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.
  • 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: 
$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 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 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: 
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: 
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: 
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: 
$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 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: 
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 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.