# Troubleshooting ## What this is This page helps you debug Hookshot by symptom, starting with the fastest checks. ## When to use it Use it whenever a Protege does not run, runs unexpectedly, or produces the wrong outcome. ## Symptom ### My Protege never runs #### Fastest checks * Confirm the source event appears in Event Feed * Confirm the integration is connected * Confirm Trigger Access is ready #### Likely causes * No event reached Hookshot * Wrong trigger source * Wrong connection scope #### Where to look in Event Feed Look for whether the event appears at all and whether any Protege was associated with it. #### Where to look in Audit If no run exists, the issue is likely earlier in the path than Audit. #### How to fix Reconnect or repair the integration, confirm the live source, and retest with a known-safe event. ## Symptom ### The event appears, but the Protege is skipped #### Fastest checks * Review the Protege description * Review readiness blockers * Confirm the event should really match the workflow #### Likely causes * The Protege is too narrow * The wrong trigger path is connected * Required access is incomplete #### Where to look in Event Feed Inspect the event entry and the associated Protege status. #### Where to look in Audit A skipped event may not produce the run result you expected, so Event Feed is the faster signal here. #### How to fix Tighten or clarify the Protege description, then verify the trigger source and required access. ## Symptom ### It says dispatching for too long #### Fastest checks * Refresh Event Feed after a short wait * Check whether Audit shows a corresponding run #### Likely causes * The event is still processing * The integration or workflow path needs attention #### Where to look in Event Feed Check whether the item progresses to a final status. #### Where to look in Audit Look for a matching run for the same Protege. #### How to fix If the state does not settle, review the integration health, recent setup changes, and rerun a controlled test. ## Symptom ### The Protege ran, but the result is wrong #### Fastest checks * Review the Protege description * Confirm the destination boundary * Confirm Tool Access covers the intended action path #### Likely causes * The Protege is too broad * The wrong destination or scope is configured * The workflow needs clearer constraints #### Where to look in Event Feed Confirm the correct source event triggered the run. #### Where to look in Audit Inspect the run outcome and compare it to the expected result. #### How to fix Narrow the scope, add stronger constraints, and retest with a safe event. ## Symptom ### Setup says a trigger is waiting for the first event #### Fastest checks * Confirm the integration is connected * Confirm the trigger source is registered * Send one known-safe event from the external app #### Likely causes * The webhook has not received its first matching event * The selected project, repo, channel, team, or portfolio is not the one being tested * The integration was connected but trigger setup was not finished #### Where to look in Event Feed Look for the first event from the selected source. If no event appears, the issue is still in the source or trigger path. #### Where to look in Audit Audit will only help after Hookshot has routed the event into a run. #### How to fix Send a controlled event from the exact configured source. If nothing appears, review Trigger Access and reconnect or repair the integration. ## Symptom ### A health check or deployment probe is failing #### Fastest checks * Check the service health endpoint * Confirm the service can reach Postgres * Confirm Temporal is reachable for worker readiness #### Likely causes * Database connectivity is unavailable * Temporal connectivity is unavailable * The worker heartbeat is stale #### How to fix For the Temporal worker, use the HTTP readiness and liveness endpoints configured for the deployment. Readiness checks whether dependencies are reachable; liveness checks whether the worker heartbeat is fresh. ## Next step * [Event Feed](/event-feed.md) * [Audit](/event-feed/audit.md) * [Readiness and blockers](/create-a-protege/readiness-and-blockers.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tryprotege.com/event-feed/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.