Troubleshooting

Common issues and solutions when running the OpenHound GitHub collector.

This guide covers common issues encountered when running the OpenHound GitHub collector and how to resolve them.

Docker Compose Issues

Docker commands fail from WSL

If you run OpenHound from Windows with WSL and Docker commands fail or cannot find the Docker daemon, verify Docker Desktop WSL integration.

1. Open Docker Desktop.

2. Click Settings > Resources > WSL integration.

3. Enable integration for the WSL distribution where you run OpenHound.

4. Return to your WSL terminal and run:

   docker compose version
   

More than one collector starts

The Enterprise Docker Compose example defines services for GitHub, Jamf, and Okta. Start only the service for the extension you configured.

docker compose up -d scheduler-github

If you run docker compose up -d without a service name, Docker starts every service in the Compose file.

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

Private Key Issues

If you encounter errors related to the private key:

• Ensure the .pem file path is correct and accessible.
• When you run OpenHound with Docker Compose, ensure key_path points to the mounted container path, such as /app/.dlt/github.pem.
• 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.

Enterprise and organization parameter mismatch

The GitHub collector uses different parameters for enterprise-scoped and organization-scoped collection:

Collection scope	Required parameter
Enterprise GitHub App	enterprise_name
Organization GitHub App or PAT	org_name

If collection fails after authentication succeeds, confirm that the configured parameter matches the GitHub authentication method.

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 a GitHub App authentication method instead of a PAT for higher rate limits.
2. Run collection during off-peak hours.
3. Tune the HTTP request parameters so OpenHound waits out rate limits instead of failing the run.

Large Environment Issues

Collection Takes Too Long

For organizations with thousands of repositories, a full collection can take several hours.

1. Use a GitHub App authentication method for higher rate limits.
2. Run collection during off-peak hours.
3. Tune the HTTP request parameters.

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

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 collector version, full error message, and approximate environment size.
3. Join the #github-og channel on the BloodHound Community Slack.