> For the complete documentation index, see [llms.txt](https://docs.stoobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow/troubleshooting.md).

# Troubleshooting

{% hint style="info" %}

* \<SERVICE-NAME> can be found in `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/services`
* \<WORKFLOW-NAME> by default can either be record, mock, or test
  {% endhint %}

## After Running a Workflow

{% stepper %}
{% step %}
**Ensure two workflows are not running at the same time**

* Bring one workflow down before running another
  * e.g. `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/down`
    {% endstep %}

{% step %}
**Double check expected containers are running**

* Ensure the proxy container for each service is running
  * e.g. `docker ps | grep <WORKFLOW-NAME>-<SERVICE-NAME>.proxy-1`
  * To learn about which containers should be running, see [here](/core-concepts/scaffold/validation.md)
* If the workflow is either `record` , `mock` , or `test` ensure the gateway service is running
  * e.g. `docker ps | grep <WORKFLOW-NAME>-gateway.service-1`
    {% endstep %}

{% step %}
**Gather logs to search for errors**

* To view init logs run:
  * `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/logs options="--container init"`
* To view service logs run:
  * `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/logs`
    {% endstep %}

{% step %}
**Gather logs to trace request**

* Ensure that a request gets routed to the correct service container
  * To learn more about request service flow, see [here](/core-concepts/scaffold/workflow.md)
* To view service logs run:
  * `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/logs`
* To view gateway logs run:
  * `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/logs options="--container service --service gateway"`
    {% endstep %}

{% step %}
**Use validate workflow command**

* To learn more about the command, see [here](/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow/troubleshooting/validating.md)
  {% endstep %}
  {% endstepper %}

## After Unexpected 5xx Error

{% stepper %}
{% step %}
**Double check system configuration**

* `/etc/hosts` contains the correct hostname(s)
  {% endstep %}

{% step %}
**Ensure CA certs are installed**

* Run either of the following:
  * `make -f .stoobly/services/Makefile ca-cert install`
  * `stoobly-agent ca-cert install`
  * For manual installation, see <https://docs.mitmproxy.org/stable/concepts-certificates/>
    {% endstep %}
    {% endstepper %}

## After 499 Status Code (Mock Not Found)

{% stepper %}
{% step %}
**Double check if the correct scenario is used**

* Double check if request exists in the scenario
* By default the UI is configured to run on <http://localhost:4200>
  {% endstep %}

{% step %}
**Double check rewrite rules**

* See `.stoobly/services/<SERVICE-NAME>/<WORKFLOW-NAME>/init`
* To learn more about rewrite rules, see [here](/core-concepts/agent/proxy-settings/rewrite-rules.md)
  {% endstep %}

{% step %}
**Double check lifecycle hooks**

* See `.stoobly/services/<SERVICE-NAME>/<WORKFLOW-NAME>/lifecycle_hooks.py`
* To learn more about lifecycle hooks, see [here](/core-concepts/agent/lifecycle-hooks.md)
  {% endstep %}

{% step %}
**Double check match rules**

* See `.stoobly/services/<SERVICE-NAME>/<WORKFLOW-NAME>/init`
* To learn more about match rules, see [here](/core-concepts/agent/proxy-settings/match-rules.md)
  {% endstep %}

{% step %}
**Gather logs to confirm correct application of rules (if any)**

* Search in the service logs to see if any rewrite rules are applied
* To view service logs run:
  * `make -f .stoobly/services/Makefile <WORKFLOW-NAME>/logs`
    {% endstep %}
    {% endstepper %}

## After Incorrect Response Returned

{% stepper %}
{% step %}
**Double check if the correct scenario is used**

* Double check if request exists in the scenario
* By default the UI is configured to run on <http://localhost:4200>
  {% endstep %}

{% step %}
**Create an Endpoint to enable component specific matching**

* To learn more, see [here](/experimental/experimental-features/endpoints.md)
  {% endstep %}
  {% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.