---
title: Troubleshooting
description: Solutions to the most common Sencho setup and runtime problems.
---

## Containers won't start after deploy

**Symptom:** You click Deploy and containers immediately exit or never appear.

**Check:** Open the [Host Console](/features/host-console) and run:

```bash
docker compose -f /path/to/your/stack/compose.yaml logs
```

The most common causes:

- **Missing environment variable** - a required variable in your `.env` file is empty or has the wrong name.
- **Port already in use** - another container or host process is bound to the same port. Change the host port in the compose file.
- **Volume path does not exist** - a bind-mount path on the host doesn't exist yet. Create the directory manually.

---

## The 1:1 path rule - volumes resolve to wrong paths

**Symptom:** Stacks deploy but relative volume paths (e.g. `./config:/config`) point to the wrong location inside the container, or `docker compose` exits with a path error.

**Cause:** Your `COMPOSE_DIR` is mounted at a different path inside the Sencho container than it has on the host.

**Fix:** Your compose volume mount and `COMPOSE_DIR` environment variable must use the **same absolute path** on both sides:

```yaml
# docker-compose.yml for Sencho itself
volumes:
  - /opt/docker:/opt/docker        # same path inside and outside
environment:
  - COMPOSE_DIR=/opt/docker
```

See [Configuration - the 1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule) for a full explanation.

---

## "Permission denied" on the Docker socket

**Symptom:** Sencho starts but shows errors accessing Docker, or the stack list is empty even though containers exist.

**Cause:** The Sencho container cannot read `/var/run/docker.sock`.

**Fix:** Ensure the socket is mounted:

```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

If you see permission errors despite a correct mount, check that the socket file exists and is a socket:

```bash
ls -la /var/run/docker.sock
# Expected: srw-rw---- 1 root docker ...
```

Because Sencho runs as `root` inside the container by default, it can read the socket regardless of which group owns it on the host. Permission errors here usually mean the socket is not mounted at all, or it is mounted read-only.

<Note>
  If you have opted into non-root mode via `SENCHO_USER=sencho`, the entrypoint will detect the socket's GID and add the sencho user to the matching group automatically. Socket errors in that mode most often mean the `SENCHO_USER` was set to an account that does not exist inside the container.
</Note>

---

## "Permission denied" when editing or deleting a stack

**Symptom:** Saving `compose.yaml`, creating a new stack, or deleting a stack fails with a permission error.

Sencho runs as `root` inside the container by default specifically to avoid this class of failure. If you are seeing permission errors, one of the following is true:

- **You are running in non-root mode** (`SENCHO_USER` is set). In this mode, filesystem writes to stack folders owned by a different UID will fail. Either `chown` the affected stack folder to the opted-in user inside the container, or unset `SENCHO_USER` to return to the default root mode.
- **The compose directory mount is read-only.** Check your Sencho container's volume mounts for a trailing `:ro` on the compose dir bind.
- **The underlying filesystem is read-only** (e.g. a full disk, a failed disk, or a remote filesystem that lost connectivity).

If you need to clean up a leftover stack directory manually:

```bash
sudo rm -rf /path/to/your/compose/dir/stack-name
```

---

## Login page shows "Something went wrong"

**Symptom:** You enter credentials and get a generic error instead of being logged in.

**Possible causes and fixes:**

| Cause | Fix |
|-------|-----|
| `JWT_SECRET` is not set or is empty | Set a non-empty value for `JWT_SECRET` in your environment |
| Container restarted and session cookie is stale | Clear browser cookies for the Sencho domain and try again |
| Rate limit triggered (5 failed attempts in 15 min) | Wait 15 minutes, or restart the container to reset the limiter |

---

## Forgotten admin password

Sencho has no password recovery flow. To regain access:

1. Stop the Sencho container.
2. Delete the database file inside your data directory (`sencho.db`). You can find it in the volume you mounted to `/app/data`.

```bash
# Example, adjust the path to match your data volume mount
rm /path/to/data/sencho.db
```

3. Restart the container. Sencho will detect the missing database and re-enter first-boot setup mode, prompting you to create a new admin account.

<Warning>
  This resets all Sencho configuration: users, nodes, alert rules, notification settings, and labels. Your Docker stacks and their compose files are not affected (they live in `COMPOSE_DIR`, not the database). Sencho will re-discover your stacks on the next sidebar scan.
</Warning>

---

## WebSocket connections fail (logs/console not streaming)

**Symptom:** The log viewer or host console shows a spinner that never resolves, or you see "Disconnected" immediately after connecting.

**Cause:** A reverse proxy is not forwarding WebSocket upgrade headers.

**Fix:** Add WebSocket support to your proxy config:

```nginx
# Nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
```

Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends, so no extra config is needed.

---

## Remote node shows "Offline" or "Unknown"

**Symptom:** A node you added shows a red or gray status dot.

**Checks in order:**

1. **Is the remote Sencho instance running?** SSH to that machine and verify.
2. **Is the API URL correct?** It must include the protocol and port (e.g. `http://192.168.1.20:3001`). Open it in a browser; you should see a JSON response from `/api/health`.
3. **Is the token correct?** Tokens are long JWT strings. Even one missing character will cause auth to fail. Regenerate the token on the remote instance and update the node config.
4. **Is there a firewall blocking the port?** The primary Sencho host must be able to reach the remote host's Sencho port.

To re-test connectivity after making changes, open **Profile > Settings > Nodes** and click the **wifi icon** on the node row.

---

## License tier shows the wrong name

**Symptom:** The license card in **Settings > License** shows the wrong tier name (e.g. "Sencho Skipper" when you purchased Admiral).

**Cause:** Older versions of Sencho could misidentify certain license variant names from the payment provider.

**Fix:** Update to the latest version of Sencho and restart. The correct tier name will appear automatically in **Settings > License**.

---

## Paid features are still locked after activation

**Symptom:** Features remain locked even though you activated a valid license key.

**Checks in order:**

1. Open **Settings > License** and verify it shows your license as **active** with the correct tier name.
2. If the tier shows "Skipper" but you purchased Admiral, this is the same variant identification issue described above. Update Sencho to the latest version to resolve it.
3. If the tier shows correctly but features are still locked, restart the Sencho container.

---

## "No billing portal available" when clicking Manage Subscription

**Symptom:** Clicking **Manage Subscription** shows an error about no billing portal being available.

**Possible causes:**

- **Lifetime license:** Lifetime licenses do not have a billing portal. This is expected behavior. In the latest version, the **Manage Subscription** button is hidden for lifetime licenses.
- **Network issues:** If your Sencho instance cannot reach the internet, the billing portal URL cannot be fetched. Check your instance's outbound connectivity and try again.

---

## Paid features return 403 on remote nodes

**Symptom:** A Skipper or Admiral feature works on the local node but returns a 403 error when you switch to a remote node.

**Checks in order:**

1. **Is your primary instance licensed?** Open **Profile > Settings > License** on the primary instance and verify it shows an active Skipper or Admiral license. Remote nodes inherit the primary's tier; if the primary is on Community, all remote nodes will be Community too.
2. **Is the remote node's token valid?** An expired or revoked token prevents the license tier from being transmitted. Regenerate the token on the remote instance and update the node config on the primary.
3. **Is the remote node running an up-to-date version of Sencho?** Distributed license enforcement requires both the primary and remote instances to be on a compatible version. Update the remote node if it's outdated.
4. **Are you accessing the remote node directly?** If you navigate directly to the remote Sencho instance's URL (bypassing the primary), it uses its own local license. License inheritance only works through the primary's proxy.

---

## Scan stacks folder doesn't find my stacks

**Symptom:** You placed Docker Compose files in the stacks directory and clicked the scan button, but "No new stacks found" appears.

**Checks in order:**

1. **Is the compose file in a subdirectory?** Sencho only discovers stacks inside subdirectories of `COMPOSE_DIR`. A loose `compose.yaml` sitting directly in the root of `COMPOSE_DIR` is ignored. Each stack must be in its own folder (e.g. `COMPOSE_DIR/my-app/compose.yaml`).

2. **Is the compose file named correctly?** Sencho recognizes these filenames only:
   - `compose.yaml`
   - `compose.yml`
   - `docker-compose.yaml`
   - `docker-compose.yml`

   Other names (e.g. `docker-compose.prod.yaml`, `stack.yaml`) are not detected.

3. **Is the directory empty or missing a compose file?** A subdirectory that exists but contains no recognized compose file will not appear. Add a valid compose file to the directory.

4. **Is the stack already tracked?** Stacks that already appear in the sidebar are not reported again. The scan only reports *changes* since the last time the list was loaded.

---

## Stack shows "--" instead of UP even though containers are running

**Symptom:** A stack appears in the sidebar with no status indicator (shown as "--"), but clicking on it reveals running containers with active stats.

**Cause:** The sidebar status check matches containers by their Docker Compose project label. A mismatch can happen when:

- The compose file declares a top-level `name:` field that overrides the default project name.
- Containers were created before Sencho reorganized compose files into subdirectories, so their labels still reference the old layout.

**Fix:** Update to the latest version of Sencho. The status check uses multiple fallback strategies (project name mapping, service name, and config file paths) to match containers regardless of how they were originally started.

---

## Network creation fails

**Symptom:** Clicking **Create** in the Create Network dialog returns an error about a missing or invalid name.

**Rules for network names:**

- Names must be non-empty and cannot contain only whitespace.
- Allowed characters: letters, numbers, hyphens (`-`), underscores (`_`), and dots (`.`).
- Names must start with a letter, number, or underscore. They cannot start with a dot or hyphen.

| Name | Valid? | Reason |
|------|--------|--------|
| `my-network` | Yes | |
| `app_net.v2` | Yes | |
| `.hidden` | No | Cannot start with a dot |
| `-leading` | No | Cannot start with a hyphen |
| `my network` | No | Spaces not allowed |
| `net/work` | No | Slashes not allowed |

---

## Cannot delete a system network (bridge, host, none)

**Symptom:** The delete button is missing or disabled for certain networks.

**Expected behavior:** Docker system networks (`bridge`, `host`, `none`) cannot be deleted. They are created by the Docker daemon and are required for normal operation. Sencho intentionally hides the delete action for these networks.

If you need to clean up unused *user-created* networks, use the **Prune Dead Networks** button in the Quick Clean section at the top of the Resources page.

---

## Network inspect shows "Network not found"

**Symptom:** Clicking the inspect icon (eye) on a network row returns a "not found" error.

**Cause:** The network was deleted between the time the list loaded and when you clicked inspect. This can happen if another user or an external tool removed the network.

**Fix:** Switch to a different tab and back (or click another nav item and return to Resources) to reload the network list.

---

## Network topology is empty

**Symptom:** Switching to the **Topology** view mode on the Networks tab shows "No user-created networks found" even though you have running containers.

<Note>
  Network Topology requires a Skipper or Admiral license.
</Note>

**Possible causes:**

- **All containers are on system networks only.** The topology view excludes Docker's built-in `bridge`, `host`, and `none` networks. If your containers only use the default bridge, they won't appear. Create a custom network in your compose file to see them in the topology.
- **No containers are connected.** Networks with zero connected containers still appear as nodes, but if you have no user-created networks at all, the view will be empty.

**Fix:** Define custom networks in your compose files:

```yaml
networks:
  frontend:
  backend:

services:
  web:
    networks: [frontend, backend]
  api:
    networks: [backend]
```

After deploying, the topology will show these networks and their connected containers.

---

## "Open App" doesn't appear in the context menu

**Symptom:** You right-click a stack in the sidebar but "Open App" is not listed.

**Cause:** The **Open App** option only appears when both conditions are met:

1. The stack is **running** (status shows UP).
2. At least one container in the stack has a **published port** (a port mapped to the host).

If your container uses host networking, doesn't expose ports, or only binds to internal Docker networks, the option won't appear. You can still access the app manually by checking the container's port mappings in the stack detail view.

---

## Remote update button does not appear

**Symptom:** A remote node in Fleet View has no **Update** button even though it is running an older version.

**Cause:** The remote node does not advertise the `self-update` [capability](/features/node-compatibility). This happens when the node is not running inside a Docker Compose-managed container, or the Docker socket is not mounted.

**Fix:** Ensure the remote node's `docker-compose.yml` includes the socket volume mount:

```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

Nodes running very old Sencho versions that predate the capability system need to be updated manually first. After that, future updates can be triggered from the dashboard.

---

## Remote update times out

**Symptom:** After clicking **Update** on a remote node, the status changes to **Timed out** instead of **Updated**.

**Cause:** The gateway waits up to 5 minutes for the remote node to come back online after triggering the update. A timeout can happen if:

- The image pull is very slow on the remote host (large image, slow connection)
- The container failed to restart after pulling
- Network connectivity was lost between the gateway and remote node during the update

**Fix:**

1. Hover over the **Timed out** badge to see the error message for more detail.
2. Click the **Retry** button (circular arrow) next to the badge to try again.
3. If the issue persists, click **Dismiss** (X button) to clear the state, then check the Docker logs on the remote host directly.
4. You can also click **Recheck** in the dialog footer to clear all failed states and re-scan every node.
5. As a last resort, update manually on the remote host:

```bash
docker compose pull && docker compose up -d
```

<Note>
  Update state is tracked in memory on the gateway. Restarting the gateway clears all stuck states automatically.
</Note>

---

## Remote update shows "Failed"

**Symptom:** After clicking **Update**, the status shows **Failed** with an error message.

**Cause:** There are two common scenarios:

1. **Immediate failure:** The gateway could not reach the remote node's update endpoint, or the remote node rejected the request. Common reasons include network issues, expired API tokens, or the remote node not supporting self-update.

2. **Delayed failure (after ~90 seconds):** The update was accepted by the remote node, but the node never restarted. This usually means the image pull failed on the remote host. The error message will read: *"Update may have failed. The node is still running and its version has not changed."*

**Fix:**

1. Hover over the **Failed** badge to see the specific error message.
2. For immediate failures: verify the remote node is online and the API token is valid.
3. For delayed failures: check the Docker logs on the remote host. The pull may have failed due to network issues, registry authentication, or disk space.
4. Click **Retry** to attempt the update again after resolving the issue.

---

## Local self-update fails with "env file not found"

**Symptom:** After clicking **Update** on the local (gateway) node, the status changes to **Failed** and hovering over the badge shows an error like:

```
env file /path/to/env/globals.env not found: stat /path/to/env/globals.env: no such file or directory
```

**Cause:** When Sencho updates itself, it spawns a temporary helper container that runs `docker compose up -d --force-recreate` to recreate the main container. The helper needs access to every file referenced by your `docker-compose.yml`, including `env_file` entries, `configs`, and `secrets`. If any of those files live outside the compose working directory (e.g. in a shared config folder), the helper cannot reach them unless those paths are also mounted in the main Sencho container.

**Fix:** Mount any directory that your compose file references into the Sencho container, using the **same path** on both the host side and the container side (the 1:1 path rule). Sencho automatically forwards all of its own bind mounts to the helper container during a self-update.

For example, if your compose file references `env_file: /home/user/docker/env/globals.env`, your Sencho container needs:

```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - /home/user/sencho/data:/app/data
  - /home/user/docker:/home/user/docker  # shared config directory
```

After adding the missing volume mount, restart Sencho and retry the update.

<Note>
  The 1:1 path rule applies here: the host path and container path must match for any directory your compose file references. This ensures the helper container can resolve file paths exactly as they are written in the compose file.
</Note>

---

## First remote update always times out on old nodes

**Symptom:** After triggering a remote update on a node running a very old Sencho version (pre-v0.39.3), the node successfully restarts with the new version, but the dashboard shows **Timed out** or **Failed** instead of **Updated**.

**Cause:** The gateway detects update completion using three signals: a version change, a process restart (via `startedAt`), or temporary offline detection. Nodes running Sencho versions older than v0.39.3 report their version as `"unknown"` and do not include `startedAt` in their metadata. If the container restart is brief enough that the gateway does not detect the node going offline, none of the three signals fire.

**Fix:** This only affects the **first** update from a very old version. After the update completes (even though the dashboard may show "Failed" or "Timed out"), the remote node will be running the latest version with proper version reporting and restart detection. Future updates triggered from the dashboard will complete normally.

1. Click **Dismiss** on the badge to clear the state.
2. Click **Recheck** to verify the node is now running the latest version.
3. If the node still shows "unknown", update it manually on the remote host:

```bash
docker compose pull && docker compose up -d
```

---

## Remote node version shows "unknown"

**Symptom:** A remote node appears online in the Fleet View but its version badge is missing or the Node Updates modal shows "unknown" in the current version column.

**Common causes:**

1. **Network issue:** The gateway cannot reach the remote node's `/api/meta` endpoint. Check that the API URL configured for the node is correct and accessible from the gateway host.
2. **Old Sencho version:** Nodes running Sencho versions older than v0.39.0 do not report a version in their metadata. Update the remote node manually to resolve this.
3. **Development build:** If running from source, ensure you have run `npm install` in the backend directory so the `predev` hook regenerates the version file.

**To verify:** Open your browser's developer tools and check the response from `GET /api/fleet/update-status`. Each node's `version` field should contain a semver string (e.g., `"0.39.4"`). If it shows `null`, the gateway could not determine the remote's version.

---

## Stack labels are not visible in the sidebar

**Symptom:** You assigned labels to stacks but no label pills appear in the sidebar.

**Checks:**

1. **License tier**: Labels require a Skipper or Admiral license. Verify your tier in **Profile > Settings > License**.
2. **At least one label must exist**: Labels are managed in **Profile > Settings > Labels**. Create at least one label before assigning it to stacks.
3. **Downgrade**: If you downgraded from a paid tier to Community, the label UI is hidden but your data is preserved. Upgrading again restores all labels and assignments.

---

## Notification routing rule matches but alerts still go to global channels

**Symptom:** You created a routing rule for a stack, but alerts from that stack still arrive on the global Discord/Slack/Webhook channels.

**Checks:**

1. **Stack name match**: The stack name in the routing rule must match exactly. Stack names are case-sensitive and correspond to the directory name in your compose folder.
2. **Rule is enabled**: Check that the route's toggle is turned on in **Profile > Settings > Routing**.
3. **License tier**: Notification Routing requires an Admiral license. Skipper and Community users can only use global channels.

---

## LDAP connection refused

**Symptom:** Enabling LDAP SSO and testing the connection fails with a connection error.

**Fix:** Verify the LDAP server is reachable from the Sencho container. If LDAP is on the host machine, use `host.docker.internal` (Docker Desktop) or the host's LAN IP address, not `localhost`.

---

## TLS certificate errors (LDAP)

**Symptom:** LDAP connection test fails with a TLS/certificate error.

**Fix:** If your LDAP server uses a self-signed certificate, toggle off "Verify TLS certificate" in **Profile > Settings > SSO**. For production, install a trusted certificate instead.

---

## OAuth callback URL mismatch

**Symptom:** After authenticating with Google, GitHub, or Okta, the provider returns a "redirect URI mismatch" error.

**Fix:** The redirect URI registered in your identity provider must exactly match what Sencho sends. Check:

1. `SSO_CALLBACK_URL` is set to your external URL (e.g., `https://sencho.example.com`)
2. The callback URL in your provider's settings is `https://sencho.example.com/api/auth/sso/oidc/<provider>/callback`
3. Protocol matches: don't mix `http` and `https`

---

## SSO buttons not appearing on login page

**Symptom:** You configured an SSO provider but the login page shows no SSO buttons.

**Cause:** SSO providers only appear on the login page when they are both **configured** (saved with valid credentials) and **enabled** (toggle is on).

**Fix:** Open **Profile > Settings > SSO** and verify the provider has an **Active** badge and its toggle is enabled.

---

## Image update checks skip some stacks

**Symptom:** Some stacks in the sidebar never show the "Update available" badge, even though newer images exist on the registry.

**Possible causes:**

- **Build-only services:** Services in your compose file that use `build:` without an `image:` key are skipped. Only services with a remote image reference are checked.
- **Unresolvable variables:** If a service's image uses `${VAR}` interpolation and the variable has no default value and is not defined in the stack's `.env` file, the image reference cannot be resolved and is skipped. Add a default value (e.g., `${TAG:-latest}`) or define the variable in the stack's `.env` file.
- **Image not pulled locally:** Stacks that have never been deployed (no local image on disk) will not show update badges because there is no local digest to compare against the registry. Deploy the stack at least once to enable update detection.

---

## "Check for updates" shows rate-limit error

**Symptom:** Clicking "Check for updates" shows a toast error about waiting before checking again.

**Cause:** Manual update checks are rate-limited to prevent excessive requests to container registries. The cooldown between manual checks is 2 minutes. Wait for it to elapse before checking again. Automatic background checks run every 6 hours regardless of this limit.

---

## Dashboard stats briefly lag behind external changes

**Symptom:** You start, stop, or restart a container directly via `docker` CLI (not through Sencho), and the Sencho dashboard takes a couple of seconds to reflect the change.

**Cause:** Sencho caches expensive dashboard queries (container counts, stack statuses, host CPU/memory) for a few seconds to keep the UI responsive under heavy polling. Changes made *inside* Sencho invalidate the cache immediately, so your own actions are always reflected instantly. Changes made *outside* Sencho (e.g. another `docker compose up` on the host) fall through the cache window.

**Fix:** Wait a few seconds, or switch tabs and back to force a fresh read. This is working as intended and has no effect on correctness, only on freshness.

---

## Checking the health endpoint

Sencho exposes a health endpoint for monitoring and container health checks:

```bash
curl http://localhost:3000/api/health
# {"status":"ok","uptime":12345.67}
```

A `200` response confirms the backend is running. Use this endpoint in your uptime monitor or load balancer health check.

---

## Getting logs from the Sencho container itself

```bash
docker logs sencho
# or, to follow:
docker logs -f sencho
```

The backend logs all route errors and service failures to stdout. This is the first place to look when the UI shows an error with no useful message.
