Skip to content

Troubleshooting

Start with the command closest to the failing layer.

Install/setup -> license/link -> SSH/server init -> DNS/HTTPS -> deploy -> runtime

Install

er command not found

Check Homebrew installed the formula and that your shell can see Homebrew's bin directory:

brew list | grep easyrunner
er --help
Formula not found

Check the tap:

brew tap | grep easyrunner

License

No valid license

Install and validate the license:

er license install ~/Downloads/easyrunner-license.jwt
er license status
er license validate
GitHub deploy-key setup fails

Check GitHub link status and confirm the app uses an SSH repo URL:

er link github --status
er app show-details my-app my-server
Cloudflare did not create DNS

Check the Cloudflare link, token scopes, and whether the domain belongs to that account:

er link cloudflare production --status
er link status

SSH and Server Init

EasyRunner cannot connect to the server

Check that the server is reachable and the EasyRunner public key is authorized:

er server show-ssh-key my-server
er server ssh-connect-test my-server --username root
Server verification fails

Re-run verification and inspect server logs:

er server verify my-server
er server logs my-server --lines 200

DNS and HTTPS

The app domain does not resolve

Confirm the DNS A record points at the web host IP:

er app show-details my-app my-server
er server list
HTTPS certificate fails

Make sure DNS is correct before deploy and ports 80 and 443 are open. Then check Caddy logs:

er server logs my-server --lines 200

Deploy Flow

Flow A build fails

Check that the repo has a Dockerfile or Containerfile and .easyrunner/docker-compose-app.yaml. Then review deploy output and app logs.

Flow B uses old Compose-format settings

Re-store the Compose-format file and deploy again:

er app update-details my-app my-server --compose-file ./docker-compose.yaml
er app deploy my-app my-server
Private registry pull fails

For GHCR, check reserved secrets and PAT scope:

er app secret list my-app
er app secret set my-app EASYRUNNER_GHCR_USERNAME
er app secret set my-app EASYRUNNER_GHCR_PAT

Runtime

App is deployed but not responding

Check app status, logs, and the internal port label:

er app status my-app my-server
er app logs my-app my-server --lines 200

Confirm xyz.easyrunner.appContainerInternalPort matches the port your app listens on inside the container.