📝 Adds server error + solution to troubleshooting

2026-05-19 07:54:54 -04:00 · 2026-04-12 19:08:09 +01:00
parent aceb4ee47e
commit 21e7a67b3d
1 changed files with 133 additions and 2 deletions
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -8,19 +8,23 @@
 ## Contents

 - [Config not saving](#config-not-saving)
+- [Unable to write conf.yml: EACCES: permission denied](#unable-to-write-confyml-eacces-permission-denied)
 - [Refused to Connect in Web Content View](#refused-to-connect-in-modal-or-workspace-view)
 - [404 On Static Hosting](#404-on-static-hosting)
 - [404 from Mobile Home Screen](#404-after-launch-from-mobile-home-screen)
+- [404 On Multi-Page Apps](#404-on-multi-page-apps)
 - [Yarn Build or Run Error](#yarn-error)
 - [Remote Config Not Loading](#remote-config-not-loading)
+- [High CPU or RAM Usage on Startup](#high-cpu-or-ram-usage-on-startup)
 - [Heap limit Allocation failed](#ineffective-mark-compacts-near-heap-limit-allocation-failed)
 - [Command failed with signal "SIGKILL"](#command-failed-with-signal-sigkill)
+- [Container Crashes or Restart Loop After Saving Config](#container-crashes-or-restart-loop-after-saving-config)
 - [Auth Validation Error: "should be object"](#auth-validation-error-should-be-object)
 - [App Not Starting After Update to 2.0.4](#app-not-starting-after-update-to-204)
 - [Keycloak Redirect Error](#keycloak-redirect-error)
 - [OIDC or Keycloak failure on numeric client IDs](#oidc-or-keycloak-failure-on-numeric-client-ids)
 - [Docker Directory Error](#docker-directory)
- [Config not Saving on Vercel / Netlify / CDN](#user-content-config-not-saving-on-vercel--netlify--cdn)
+- [Config not Saving on Vercel / Netlify / CDN](#config-not-saving-on-vercel--netlify--cdn)
 - [Config Not Updating](#config-not-updating)
 - [Config Still not Updating](#config-still-not-updating)
 - [Styles and Assets not Updating](#styles-and-assets-not-updating)
@@ -33,8 +37,11 @@
 - [Warnings in the Console during deploy](#warnings-in-the-console-during-deploy)
 - [Docker Login Fails on Ubuntu](#docker-login-fails-on-ubuntu)
 - [Status Checks Failing](#status-checks-failing)
+- [Healthcheck Failing in Docker](#healthcheck-failing-in-docker)
 - [Diagnosing Widget Errors](#widget-errors)
 - [Fixing Widget CORS Errors](#widget-cors-errors)
+- [CORS Proxy connect ECONNREFUSED or ENOTFOUND](#cors-proxy-connect-econnrefused--or-getaddrinfo-enotfound-)
+- [CORS Proxy Target-URL host blocked or scheme rejected](#cors-proxy-target-url-host--is-blocked--must-use-http-or-https)
 - [Widget Shows Error Incorrectly](#widget-shows-error-incorrectly)
 - [Weather Forecast Widget 401](#weather-forecast-widget-401)
 - [Widget Displaying Inaccurate Data](#widget-displaying-inaccurate-data)
@@ -43,6 +50,7 @@
 - [Unsupported Digital Envelope Routines](#unsupported-digital-envelope-routines)
 - [How to Reset Local Settings](#how-to-reset-local-settings)
 - [How to make a bug report](#how-to-make-a-bug-report)
+- [Public IP Widget not working for ipinfo or ipquery providers](#public-ip-widget-not-working-for-ipinfo-or-ipquery-providers)
 - [How-To Open Browser Console](#how-to-open-browser-console)
 - [Git Contributions not Displaying](#git-contributions-not-displaying)

@@ -67,6 +75,29 @@ After saving, the frontend will recompile, which may take a couple seconds (or a

 ---

+## Unable to write conf.yml: `EACCES: permission denied`
+
+Most commonly the `conf.yml` file itself is mounted read-only, or its mode is `444`. Make it writable on the host:
+
+```bash
+chmod 644 /path/to/your/conf.yml
+```
+
+As for backups, Dashy creates a timestamped backup of the existing config in `user-data/config-backups/` before writing the new one. If the host filesystem prevents that copy (read-only mount, wrong UID/GID, no execute bit on the parent directory), the save aborts before touching the live config.
+
+Check that the user-data volume is writable by the container user:
+
+```bash
+docker exec -it dashy id
+docker exec -it dashy ls -la /app/user-data
+```
+
+If you bind-mount from the host, make sure the host directory is owned by the container's UID (or world-writable). You can also override the backup location with the `BACKUP_DIR` env var.
+
+And, if you intentionally want a read-only config and don't want users to even attempt saves, set `appConfig.preventWriteToDisk: true` in `conf.yml` - Dashy will then disable both the endpoint, and the save button itself, to make the experience more explicit.
+
+---
+
 ## `Refused to Connect` in Modal or Workspace View

 This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements.
@@ -176,6 +207,31 @@ If it is a remote service, that you do not have admin access to, then another op

 ---

+## High CPU or RAM Usage on Startup
+
+When the Dashy container first starts, it runs a Vue production build in parallel with the server. This is **a one-time cost per container start**, but it briefly uses around **1–1.5 GB of RAM and 100% of one CPU core** for anywhere from 30 seconds to several minutes (depending on host speed). On Pi-class hardware or VMs with less than 1 GB of RAM, this spike can be enough to lock up the host.
+
+**To work around it:**
+
+1. **Allocate at least 1 GB of RAM to the container** — 2 GB is recommended on Raspberry Pi or low-powered VMs. Anything below 512 MB is unlikely to complete the first build.
+2. **Set explicit Docker resource limits** so the build can't starve other services on the same host:
+   ```yaml
+   services:
+     dashy:
+       image: lissy93/dashy:latest
+       deploy:
+         resources:
+           limits:
+             memory: 2g
+             cpus: '1.5'
+   ```
+3. **Wait it out** — once the build completes, idle CPU drops to near zero and idle RAM is typically under 100 MB. If you watch `docker stats`, you'll see the spike taper off.
+4. If the spike never tapers (i.e., Dashy stays at 100% CPU forever and never serves the page), see [Heap limit Allocation failed](#ineffective-mark-compacts-near-heap-limit-allocation-failed) below — that usually means the build was killed mid-way and is being retried.
+
+See also: [#1585](https://github.com/Lissy93/dashy/issues/1585), [#969](https://github.com/Lissy93/dashy/issues/969), [#1500](https://github.com/Lissy93/dashy/issues/1500), [#877](https://github.com/Lissy93/dashy/issues/877)
+
+---
+
 ## Ineffective mark-compacts near heap limit Allocation failed

 If you see an error message, similar to:
@@ -190,7 +246,7 @@ If you see an error message, similar to:
 FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 ```

-This is likely caused by insufficient memory allocation to the container. When the container first starts up, or has to rebuild, the memory usage spikes, and if there isn't enough memory, it may terminate. This can be specified with, for example: `--memory=1024m`. For more info, see [Docker: Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/).
+This is likely caused by insufficient memory allocation to the container. When the container first starts up, or has to rebuild, the memory usage spikes, and if there isn't enough memory, it may terminate. This can be specified with, for example: `--memory=1024m`. For more info, see [Docker: Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/). For more context on what the spike is, see [High CPU or RAM Usage on Startup](#high-cpu-or-ram-usage-on-startup) above.

 See also: [#380](https://github.com/Lissy93/dashy/issues/380), [#350](https://github.com/Lissy93/dashy/issues/350), [#297](https://github.com/Lissy93/dashy/issues/297), [#349](https://github.com/Lissy93/dashy/issues/349), [#510](https://github.com/Lissy93/dashy/issues/510), [#511](https://github.com/Lissy93/dashy/issues/511) and [#834](https://github.com/Lissy93/dashy/issues/834)

@@ -204,6 +260,36 @@ See also [#624](https://github.com/Lissy93/dashy/issues/624)

 ---

+## Container Crashes or Restart Loop After Saving Config
+
+If your Dashy container crashes or enters a restart loop the moment you click **Save to Disk** in the editor — particularly with logs that include something like:
+
+```text
+node:_http_outgoing:652
+    throw new ERR_HTTP_HEADERS_SENT('set');
+```
+
+or:
+
+```text
+Error [ERR_STREAM_WRITE_AFTER_END]: write after end
+```
+
+This was a known crash in Dashy 3.1.0 and 3.1.1 where a partial-failure code path in the save handler would call `res.end()` twice on the same response, causing Node to throw an unhandled rejection and exit the process. Docker would then restart the container, the user would save again, and the loop repeated. Several users also reported it was reliably triggered by entering edit mode while `statusCheck: true` was set, because the periodic background traffic increased the chance of overlapping responses.
+
+**This is fixed in v3.2.13 and later**
+
+```bash
+docker pull lissy93/dashy:latest
+docker compose up -d --force-recreate
+```
+
+If you can't upgrade right away, the temporary workaround that worked for affected users is to set `statusCheck: false` under `appConfig` in your `conf.yml`. This reduces the trigger frequency without changing the underlying bug.
+
+See also: [#1945](https://github.com/Lissy93/dashy/issues/1945), [#1935](https://github.com/Lissy93/dashy/issues/1935), [#1494](https://github.com/Lissy93/dashy/issues/1494)
+
+---
+
 ## Auth Validation Error: "should be object"

 In V 1.6.5 an update was made that in the future will become a breaking change. You will need to update you config to reflect this before V 2.0.0 is released. In the meantime, your previous config will continue to function normally, but you will see a validation warning. The change means that the structure of the `appConfig.auth` object is now an object, which has a `users` property.
@@ -451,6 +537,26 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker

 ---

+## Healthcheck Failing in Docker
+
+If `docker ps` shows the Dashy container as `unhealthy`, it means the periodic healthcheck (`yarn health-check`, run every 5 minutes by default) couldn't reach the local server.
+
+### SSL-enabled Dashy
+
+The healthcheck reads the same cert paths as the main server (`/etc/ssl/certs/dashy-pub.pem` and `/etc/ssl/certs/dashy-priv.key`) to detect whether to probe HTTPS or HTTP. If you've mounted certs at non-default paths via `SSL_PUB_KEY_PATH` / `SSL_PRIV_KEY_PATH`, the healthcheck will pick those up automatically as long as those env vars are set in the container environment (not just at run time).
+
+### Custom port
+
+If you've set `PORT` to override the default 8080, the healthcheck honors the same env var, so it should work without changes. Make sure `PORT` is set in the container environment, not just in the host-side Docker port mapping.
+
+### Slow startup on weak hardware
+
+The healthcheck has a `--start-period=30s` grace period before failures count against the container. If your host takes longer than 30 seconds for the initial Vue build to complete (common on Pi 3 or similar), the first few healthchecks will fail and you may briefly see `unhealthy`. After the build finishes, subsequent checks should pass — see [High CPU or RAM Usage on Startup](#high-cpu-or-ram-usage-on-startup) below.
+
+See also: [#1410](https://github.com/Lissy93/dashy/issues/1410)
+
+---
+
 ## Widget Errors

 ### Find Error Message
@@ -514,6 +620,31 @@ For testing purposes, you can use an addon, which will disable the CORS checks.

 ---

+## CORS Proxy `connect ECONNREFUSED ...` or `getaddrinfo ENOTFOUND ...`
+
+The target host is unreachable from the Dashy container. If the target is on the same host as Dashy, **don't use `localhost`** — inside a Docker container that resolves to the container itself, not the host. Use the host's LAN IP, the Docker bridge gateway, or `host.docker.internal` (on Docker Desktop). If the target is on a different Docker network, attach Dashy to that network too.
+
+---
+
+## CORS Proxy `Target-URL host '...' is blocked` / `must use http:// or https://`
+
+To prevent the CORS proxy from being abused as a Server-Side Request Forgery vector, Dashy refuses to proxy a small number of host/scheme combinations by default:
+
+- **Cloud instance metadata services** — `169.254.169.254`, `metadata.google.internal`, and the matching IPv6 forms. These are reserved magic addresses on AWS, Azure, GCP, DigitalOcean, Hetzner, Oracle Cloud and most other providers. A widget that successfully fetches them on a cloud-hosted Dashy can leak the host's IAM credentials, so they're blocked unconditionally.
+- **Non-HTTP(S) schemes** — `file://`, `ftp://`, `gopher://`, `javascript:`, `data:`, and similar. The proxy is meant for HTTP APIs only.
+
+If you're running Dashy in a fully isolated/private environment and you've deliberately decided you want to allow these (for example, you genuinely need to query your cloud provider's metadata API from a widget), you can opt out of all proxy restrictions by setting the environment variable:
+
+```bash
+DANGEROUSLY_DISABLE_PROXY_RESTRICTIONS=true
+```
+
+The variable is named so loudly because flipping it on a Dashy instance that's exposed to anything other than fully trusted users re-opens the SSRF surface — anyone who can hit `/cors-proxy` can then use Dashy as a relay to reach internal services. **Don't set it on cloud-hosted or internet-exposed deployments.**
+
+Note that this is an all-or-nothing escape hatch, not a per-host allowlist. If you only need to reach one specific host that's currently blocked, please open a feature request describing the use case.
+
+---
+
 ## Widget Shows Error Incorrectly

 When there's an error fetching or displaying a widgets data, then it will be highlighted in yellow, and a message displayed on the UI.