DashCaddy - Troubleshooting

Authentication & CSRF (DC-1xx)

DC-100 CSRF token missing

Cause: Your browser cookie expired or was blocked. This often happens after the browser has been idle for a long time.
Fix: Hard refresh the page with Ctrl+Shift+R (or Cmd+Shift+R on Mac), then try again.

DC-101 CSRF token invalid

Cause: The security token in your browser doesn't match the one the server expects. This can happen after long idle periods or if you have multiple tabs open.
Fix: Refresh the page and try the action again.

DC-110 Authentication required

Cause: Your TOTP session has expired. Sessions last for the duration configured in your TOTP settings (default: 24 hours).
Fix: Enter your TOTP code from your authenticator app to re-authenticate.

DC-111 Invalid code

Cause: The TOTP code you entered is incorrect or has already expired. Codes refresh every 30 seconds.
Fix: Check your authenticator app for the current code. Wait for a fresh code if the current one is about to expire.

DC-120 Access denied - Tailscale required

Cause: The dashboard is configured to require a Tailscale VPN connection, and you're not currently connected.
Fix: Connect to Tailscale VPN first, then try accessing the dashboard again.

DC-200 Port is already in use

Cause: Another container or process on the host is already using the port you selected. This sometimes happens after a failed deploy leaves a stale container behind.
Fix: Use a different port in Advanced Options, or stop the conflicting service first. Check the Monitor panel to see which container is using the port.

DC-201 Failed to pull image

Cause: Docker couldn't download the container image. This is usually a network issue, or the image name/tag doesn't exist on Docker Hub.
Fix: Check your internet connection. If using a custom image, verify the image name and tag are correct.

DC-202 Container failed to start

Cause: The container was created but couldn't start or become healthy. Common reasons include misconfigured environment variables, missing volume mounts, or insufficient resources.
Fix: Check the Logs panel for container-specific error messages. Try redeploying with default settings.

DC-203 Port conflict with another service

Cause: Another DashCaddy-managed service is already using the port you specified. DashCaddy checks for this before deploying to prevent conflicts.
Fix: Choose a different port in Advanced Options, or remove the conflicting service first.

DC-210 Invalid IP address

Cause: The IP address field contains an invalid value. It must be a valid IPv4 or IPv6 address, or one of the allowed hostnames.
Fix: Use a valid IP address (e.g., 192.168.1.100) or "localhost". Leave blank to use the default.

DC-300 DNS token unavailable

Cause: The DNS server credentials have expired or are missing. DashCaddy needs valid DNS credentials to create and manage DNS records.
Fix: Go to Tokens in the toolbar, select DNS, and re-enter your DNS server credentials.

DC-301 Invalid domain/subdomain format

Cause: The domain or subdomain name contains invalid characters. Domain names can only contain lowercase letters, numbers, hyphens, and dots.
Fix: Use only letters (a-z), numbers (0-9), hyphens (-), and dots (.) in your domain name.

DC-302 Site already exists in Caddyfile

Cause: A site block for this domain is already present in the Caddy configuration file. You can't create a duplicate entry.
Fix: Edit the existing site configuration, or remove it first before creating a new one.

DC-303 Caddy reload failed

Cause: Caddy couldn't reload its configuration. This usually means there's a syntax error in the Caddyfile, or Caddy's admin API is unreachable.
Fix: Check the Logs panel for the specific Caddy error. The Caddyfile change was automatically rolled back. If the problem persists, verify Caddy is running.

DC-400 Container not found

Cause: The Docker container was removed outside of DashCaddy (e.g., via Docker Desktop or the CLI). DashCaddy still has it registered but can't find it.
Fix: Delete the service card from DashCaddy, then redeploy the app from the App Selector.

DC-401 Update failed

Cause: The container update process failed during image pull, container recreation, or startup. The old container may have been removed but the new one couldn't start.
Fix: Check the Logs panel for details. If the container is gone, redeploy the app from the App Selector.

DC-500 No credentials stored

Cause: Auto-login was attempted but no username/password is saved for this service. DashCaddy needs stored credentials to log you in automatically.
Fix: Click the key icon (🔑) on the service card to add your credentials for auto-login.

DC-501 Login failed

Cause: The stored credentials were rejected by the service. The username or password may be incorrect, or the service's auth endpoint may have changed.
Fix: Click the key icon (🔑) on the service card to update your credentials. Verify the username and password are correct by logging into the service directly first.