> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/managing-your-sfp-server/troubleshooting-common-failures.md).

# Troubleshooting common failures

Setup-time issues (TLS, SSH, webhooks, authentication redirects) are covered in [setup troubleshooting](/flxbl/sfp-server/setting-up/setting-up-sfp-server/troubleshooting.md). This page covers the failures that show up in day-2 operation, and which log answers each one.

## Where the logs are

Each service logs to its own container. Three you will read most:

```bash
sfp server logs --tenant my-app --tail 200                         # server + standard workers
docker logs <tenant>-hatchet-worker-longrunning-1 --tail 200       # long-running workers
docker logs <project>-hatchet-engine-1 --tail 200             # task-queue engine
```

The health endpoint (`GET https://<your-domain>/sfp/api`) reports per-component status and the count of active workflows — check it before and after any intervention.

## Symptom → where to look

**The server does not come up after a start or reboot.** `sfp server status` shows which service is down or restarting. Read that service's container logs first. A database container that is unhealthy blocks everything downstream — resolve it before looking at the application server. A container in a restart loop usually names its reason in the first lines after each restart.

**A workflow run is stuck or appears hung.** Open the run in the **Runs** view and check whether steps are still progressing. Long-running steps against Salesforce (package version creation, org provisioning) are governed by Salesforce's processing time and can legitimately run for tens of minutes. Compare against the previous run of the same workflow before concluding it is stuck. If steps are genuinely not progressing, read the worker logs for the run id.

**Workers behave as if they are running old code after an update.** Confirm every container is on the same image tag: `docker ps --format '{{.Names}} {{.Image}}'`. The application server and the workers share one image; if any worker shows an older tag, re-run `sfp server update` and verify again. A mixed-version stack produces inconsistent behaviour that looks like a product bug.

**No metrics or logs arriving in your observability backend.** Covered in [monitoring](/flxbl/sfp-server/managing-your-sfp-server/monitoring-for-sfp-server.md#troubleshooting) — collector configuration, authentication headers, and endpoints.

## When to contact support

Anything that requires changing database contents, editing files inside containers, or applying a patch by hand is not a self-service operation — capture the run id, the relevant log excerpt, and the output of `sfp server status`, and contact flxbl support. The same applies when a failure persists across a restart and an update with no cause visible in the logs.

{% content-ref url="/pages/t91oJESRoP8h7dmTtjTS" %}
[Monitoring for sfp server](/flxbl/sfp-server/managing-your-sfp-server/monitoring-for-sfp-server.md)
{% endcontent-ref %}


---

# 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.flxbl.io/flxbl/sfp-server/managing-your-sfp-server/troubleshooting-common-failures.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.