Troubleshooting

Troubleshooting

Aura "invalidSession" errors

Symptom: invalidSession or ERROR_INVALID_SESSION in Aura responses.

Causes:

• Session ID expired — Salesforce sessions typically last 2-12 hours depending on org settings
• Backslash corruption — some shells escape ! in session IDs (e.g., 00D...!AQE... becomes 00D...\!AQE...)

Fix: Get fresh credentials from browser DevTools. If using bash, be aware that ! triggers history expansion even inside single quotes in some configurations. Use the run_aura_tests.py helper or a Python script to set env vars.

BloodHound ingestion job canceled

Symptom: Upload job shows status "Canceled" (status code 3).

Cause: A database clear was still running when the upload started. BH CE cancels uploads that start during an active clear.

Fix: Increase --wait (default 60s). For large databases, use --wait 120 or more.

BloodHound 401 Unauthorized

Symptom: unable to validate request signature for client: resource not found

Cause: BH API token expired or deleted. Tokens are invalidated when BH restarts or when a new token is generated.

Fix: Generate a new API token in BH CE: Settings > API Tokens > Create Token. Update --bh-token-id and --bh-token-key.

Cypher query returns 404

Symptom: Cypher queries return HTTP 404.

Cause: This is by design — BH CE returns 404 when a non-mutation query matches zero results. It's not an error.

Fix: Handle 404 as "no results" in scripts. See tests/integration/bh_helpers.py for examples.

BH uppercases property values

Symptom: Cypher query WHERE o.name = "Account" returns nothing, but "ACCOUNT" works.

Cause: BH CE uppercases all string property values during ingestion.

Fix: Always use uppercase in WHERE clauses: WHERE o.name = "ACCOUNT".

API rate limiting (REQUEST_LIMIT_EXCEEDED)

Symptom: simple_salesforce raises SalesforceError: REQUEST_LIMIT_EXCEEDED.

Cause: Hit Salesforce API rate limits (varies by org edition, typically 15,000-100,000 calls/24h).

Fix: Use --rate-limit to throttle requests. For production orgs, --rate-limit 5 is a safe starting point. Also use --skip-shares and --skip-field-permissions to reduce query count.

Proxy connection errors

Symptom: ProxyError or ConnectionError when using --proxy.

Cause: Proxy is not running or not accepting connections on the specified port.

Fix: Verify the proxy is running (curl -x http://127.0.0.1:8080 https://example.com). For Burp Suite, ensure the proxy listener is active on the correct port.

Large graph ingestion timeout

Symptom: BH ingestion job shows "TimedOut" (status code 4).

Cause: Graph too large for BH's default ingestion timeout. Typically happens with Share-object data (100k+ edges).

Fix: Use --skip-shares for initial analysis, then run a separate collection with shares only if needed. Or increase BH's server-side timeout configuration.

"No users collected" in Aura mode

Symptom: Aura collector returns 0 users.

Cause: The session user may lack access to the User list view, or the org may be a scratch org with unusual sharing settings.

Fix: Try --collector both — if Aura returns 0 users, the API supplement will collect users via SOQL instead.