Troubleshooting & FAQ

Permission Denied / EACCES Errors

Symptom: Build logs show failures like npm error EACCES: permission denied, open 'package-lock.json', or Permission denied to write to .cicdlog/app.pid.

Cause: The codebase directory or logs folder belongs to a different user, or the deployment was run with root but the application is dropping privileges to the sandboxed service account user.

Solution: CICD has a built-in recursive ownership alignment mechanism. It forces all repository and configuration files to belong to the service account. If things are stuck, trigger a clean reinstall using the CLI:

cicd reinstall <service-name>

This wipes the system caching, resets file ownership recursively, resets permissions, and restarts from scratch.

PM2 Deployments Get User 'root'

Symptom: You run PM2 in run.sh, but PM2 processes are registered under the root user instead of the sandboxed service user.

Cause: PM2 stores configuration inside the home folder (~/.pm2). If the HOME and USER environment variables are not dropped correctly by the runner, PM2 defaults to root's directory.

Solution: CICD dynamically overrides HOME, USER, and utilizes credential drops during daemon fork execution. In your run.sh, make sure you write the PM2 PID into $CICD_PID_FILE:

# Inside .cicd/run.sh
pm2 delete "$CICD_SERVICE_NAME" 2>/dev/null || true
pm2 start index.js --name "$CICD_SERVICE_NAME"
pm2 pid "$CICD_SERVICE_NAME" > "$CICD_PID_FILE"

Webhook Triggers but Nothing Deploys

Symptom: Git push is made, GitHub webhook status returns success (200 OK), but the server shows no deployment logs.

Cause: The commit was pushed to a branch other than the one configured (e.g. pushed to develop while CICD monitors main), or the service is pinned to an active commit.

Solution: Check the orchestrator dashboard or list services with cicd list to check if the project is pinned. Unpin with:

cicd unpin <service-name>

No Magic Link Emails Arrive

Symptom: You set an admin email, but you do not receive magic link emails to log in to the dashboard.

Cause: Passing --admin-email requires active SMTP credentials flags (--smtp-host, --smtp-port, --smtp-user, --smtp-pass). Without them, the server cannot transmit emails.

Solution: If you do not want to configure SMTP, you can retrieve the login token directly from the server CLI. Run:

cicd token

If you want to force regenerate a new secure onboarding token, run:

cicd token --force

Alternatively, print full configuration parameters and links with cicd info.

WSL Errors: Permission denied to app.pid

Symptom: On WSL (Windows Subsystem for Linux), deployments fail on launch showing permission denied on the app.pid file.

Cause: WSL handles file permissions and user mapping differently from native Linux. Ownership synchronization during startup can cause a race condition.

Solution: Ensure your WSL user is added to the sudoers list, or run the orchestrator with --public-ip 127.0.0.1 to test locally without daemon privileges.