# Troubleshooting

Common issues and how to resolve them

- Socket path exists but is not a socket
  - Symptom: startup fails with an error that the socket path exists and is not a socket.
  - Fix: remove the file at the socket path or choose a different `--sock` path.

- Permission denied on socket directory or socket
  - Symptom: socket creation or permission setting logs warnings; clients cannot connect.
  - Fix: ensure the socket directory exists and has correct ownership/group and that `sock_perm` and `sock_gid` are configured appropriately. Consider using `chown`/`chmod` from a privileged context.

- `nginx -t` fails with `/run/nginx.pid: Permission denied`
  - Symptom: validation fails; output contains permission denied for `/run/nginx.pid`.
  - Fixes (tried by the agent):
    1. If available, provide a privileged validation wrapper (e.g. `/usr/local/sbin/yanpm-nginx-validate`) that runs `nginx -t` with appropriate privileges.
    2. Ensure the agent-runner has permission to read the main nginx configuration and `/run/nginx.pid` or allow the agent to use a writable PID override.

- Fragment file not found during validation
  - Symptom: validate returns 500 with message `Config file not found`.
  - Fix: make sure the fragment has been written via `/write_config` to the agent's internal subdirectory under `NGINX_CONFIG_DIR`, using the same `config_name` and `timestamp` as the validate call.

- Wrapper or sudo not available
  - Symptom: attempts to run `sudo -n /usr/local/sbin/yanpm-nginx-validate` fail.
  - Fix: install a wrapper script that allows unprivileged `sudo -n` validation or configure proper permissions on nginx state files.

If none of the above solves the problem, collect the logs produced by the agent (it uses `tracing`/`tracing_subscriber`) and include the exact command outputs from the validation steps when asking for help.