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

<Note>
  Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and validate against your own setup before deploying it on critical infrastructure.
</Note>

If something has broken and you want a quick "what do I do now?" overview rather than a specific symptom, start with the [Recovery guide](/operations/recovery). It walks through getting back to a working state when Sencho, a deploy, sign-in, Docker, or a remote node fails, and links back here for the details.

## High GPU usage on constrained graphics

**Symptom:** With Sencho as the active browser tab, GPU use stays high on idle, and can climb further when an update or deploy dialog is open. Other sites in the same browser stay quieter. On some dual-GPU PCs the issue shows up only when the browser is forced onto integrated graphics.

**What helped on the reported Windows configuration:** Turning on **Reduced motion** dropped idle iGPU use substantially (about 50% to about 7% in that report). **Calm** and **Reduced effects** alone did not. On that machine the issue did not appear when Windows selected the GPU or when Chrome used the discrete GPU.

**What to try:**

1. Open **Settings → Appearance → Motion & effects**.
2. Turn on **Reduced motion**. Fresh installs that use **Calm** already enable it by default. That is the first step to try for high idle GPU use on constrained graphics.
3. Optionally try **Reduced effects** as a secondary experiment (simpler glass, solid chrome, and quieter decorative masthead rails). That path is unverified for the idle-GPU symptom on its own.
4. On dual-GPU Windows PCs, you can also set the browser's GPU preference to let the OS decide, or prefer a discrete GPU, if your OS exposes that control.

**How to help validate a fix on your hardware:** Identify Chrome's GPU process (Shift+Esc), use Task Manager Details at High update speed on that PID's GPU column, leave the Sencho tab in the foreground for about 15 seconds, then record about ten one-second samples and take the median. Repeat for at least three independent runs (close and reopen the tab). Compare idle Home or Settings with Reduced motion off versus on. Separately compare an update or deploy dialog with Raw output hidden and visible. On Linux single-board devices, use one documented GPU or responsiveness counter for the whole matrix, and label CPU-only readings as secondary.

---

## 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.

Sencho connects to a remote node one of two ways: **Distributed API Proxy** mode (the primary reaches out to the remote's API URL) or **Pilot Agent** mode (the remote dials an outbound tunnel to the primary, so no inbound port is needed on the remote). The checks below cover Proxy mode; if the node is a Pilot Agent, see [Pilot Agent troubleshooting](/features/pilot-agent#troubleshooting) for the tunnel-specific causes (expired enrollment token, agent container not running, blocked outbound HTTPS).

**Checks in order (Distributed API Proxy mode):**

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. Regenerating the token on the remote instance invalidates the previous one, so update the saved node config with the new value.
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 **Settings · Infrastructure · Nodes** and click **Test Connection** on the node row. See the [Multi-Node Management troubleshooting section](/features/multi-node#troubleshooting) for additional connectivity scenarios.

---

## License tier shows the wrong name

**Symptom:** The license card in **Settings → Admiral Account** shows a tier that does not match what you purchased.

**Cause:** The tier is read from your license at validation time. A stale cached value can show after the key was activated but before the next validation cycle ran.

**Fix:** Deactivate and re-activate the key in **Settings → Admiral Account**, then restart the Sencho container. The tier is re-read on the next validation and the correct name appears automatically. If it still does not match, email `licensing@sencho.io` with your order ID.

---

## I didn't receive my trial license key after checkout

**Symptom:** You completed the Lemon Squeezy trial checkout but no license key email arrived.

**Checks in order:**

1. **Check your spam / junk folder.** Lemon Squeezy emails come from `no-reply@lemonsqueezy.com`; some providers flag them aggressively.
2. **Verify the email address you used at checkout.** If you made a typo, the key was sent to the wrong address. Contact `licensing@sencho.io` with your order ID (from the checkout receipt) and we can resend or issue a new key.
3. **Wait a few minutes.** Delivery is usually within 60 seconds but can take up to 10 minutes during peak load.
4. **Still missing after 15 minutes?** Email `licensing@sencho.io` with the transaction ID from your card statement and we will resend the key.

---

## Admiral assurance is still unavailable after activation

**Symptom:** Admiral assurance surfaces remain unavailable even though you activated a valid license key.

**Checks in order:**

1. Open **Settings → Admiral Account** and verify it shows your license as **active** with the correct tier name.
2. If the tier name does not match what you purchased, see [License tier shows the wrong name](#license-tier-shows-the-wrong-name) above.
3. If the tier shows correctly but assurance surfaces are still unavailable, 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:**

- **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.

---

## Admiral assurance returns 403 on remote nodes

**Symptom:** An Admiral assurance surface 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 **Settings → Admiral Account** on the primary instance and verify it shows an active 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. **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.

**Fix:** 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, so this usually resolves itself on the next status refresh. If it persists, confirm the containers are actually part of this stack's compose project with `docker compose -f /path/to/your/stack/compose.yaml ps`.

---

## 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 or number. They cannot start with a dot, hyphen, or underscore.

| Name | Valid? | Reason |
|------|--------|--------|
| `my-network` | Yes | |
| `app_net.v2` | Yes | |
| `.hidden` | No | Cannot start with a dot |
| `-leading` | No | Cannot start with a hyphen |
| `_leading` | No | Cannot start with an underscore |
| `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.

**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
```

After adding the mount and redeploying the remote, it advertises the capability and 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 ~3 minutes):** 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>

---

## Fleet shows Pinned and will not update the node

**Symptom:** A node row in **Node updates** shows a **Pinned** badge instead of an **Update** button, or an update attempt returns an error about the image pin.

**Cause:** The node's compose file pins Sencho by digest or uses a variable for the image value. Fleet cannot rewrite those automatically.

**Fix:** Edit the compose file to use a semver tag (for example `saelix/sencho:0.94.0`) or a floating tag such as `latest`, redeploy once if needed, then retry the update from the Node updates sheet.

---

## 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 within its 5-second timeout. Check that the API URL configured for the node is correct and accessible from the gateway host.
2. **Development build:** If running from source, ensure you have run `npm install` in the backend directory so the `predev` hook regenerates the version file.

If a triggered update never resolves once the underlying cause above is fixed, click **Dismiss** on the badge to clear the stuck state, then **Recheck** to re-scan the fleet.

**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.96.0"`). 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. **At least one label must exist**: Labels are managed in **Settings · Organization · Labels**. Create at least one label before assigning it to stacks.
2. **Assignments are saved**: Open the stack's context menu, choose **Labels**, and confirm the label is checked. Pills appear in the sidebar once at least one label is assigned.

---

## 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 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 **Settings · Notifications · Notification Routing**.

---

## 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 **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 **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:1852/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.

---

## "Could not parse command" when converting docker run

**Symptom:** The **From Docker Run** tab in the Create Stack dialog returns an error toast saying the command could not be parsed.

**Cause:** The input is not a well-formed `docker run` command, uses a flag the converter does not recognize, or exceeds the length limit.

See [Convert from a docker run command](/features/stack-management#convert-from-a-docker-run-command) for the full list of supported flags and every rejection cause, including the exact size limit and the fix for quoting issues in multi-line commands.
