Operating Workers
Everything you need day to day lives on the worker’s detail page and its three sub-pages: Builds, Application logs, and Environment.
Process Status
The Process status card reports what pm2 sees on the worker host:
- Running — the process is up
- Not running — the process is registered but stopped or crashed
- Process status unknown — the platform couldn’t get an answer
Use Refresh to re-check. The card is disabled until the worker is active, since there is no process before provisioning completes.
Restart
Restart restarts the pm2 process, picking up the current environment file. Requires the
create_workers permission.
Restart when you have:
- Saved changes on the Environment page
- A process wedged on a bad connection or a stuck consumer
- A deploy that reported success but left the process unhealthy
There is no Start or Stop control. pm2 owns the process lifecycle and restarts it if it exits, so a worker is either deployed and running or not deployed at all. To take a worker out of service permanently, delete it. To take it out temporarily, stop publishing the job types it consumes.
If a runtime action can’t reach the worker host, the page says so instead of showing stale information. That’s a transport problem, not a verdict on your worker — retry, and check the enablement panel on the project’s Workers page if it persists.
Application Logs
The Application logs page streams what your process wrote to stdout and stderr, newest first, in pages of 500 lines. Load more walks backwards through history without gaps or duplicates, even while the worker keeps logging.
“No logs yet — the worker has not written any output” means exactly that: the log stream doesn’t exist. Either the process has never produced output, or it never started. Check Process status to tell those apart.
Application logs are your worker’s own output. Build output is separate and lives on the Builds page. If a deploy succeeded but the worker misbehaves, the answer is here; if the deploy itself failed, it’s there.
Practical logging advice, since this page is your only runtime window:
- Log the job type and a correlation ID on every message you handle
- Log both the start and the outcome, so a missing outcome line marks the hang
- Log connection lifecycle events — connect, disconnect, reconnect attempts
- Don’t log secrets or full message payloads; they’ll sit in the log stream
Builds
Every push to main triggers the pipeline. The Builds page lists up to the 25 most
recent runs with status, timing, trigger, and the source revision that produced them.
Open a single run to see:
- Build status and per-phase breakdown with durations, so you can see which phase failed
- Up to 1000 lines of build log output
- A deep link into the AWS console for the full log, when you need more
Build and phase statuses come straight from the underlying build service, so you get raw
values like SUCCEEDED, FAILED, and IN_PROGRESS.
An empty build list on a worker that isn’t finished provisioning is normal — the pipeline doesn’t exist yet.
Reading a Failed Build
| Where it failed | Usual cause |
|---|---|
INSTALL phase | A dependency won’t resolve on a clean checkout, or npm install fails |
BUILD phase | No build script, or the build command errored |
UPLOAD_ARTIFACTS phase | The build produced nothing to ship |
| Deploy stage, after build | Artifacts were built, but shipping them or starting pm2 failed |
A deploy that succeeds while the process never comes up is almost always the pm2 naming rule. See Writing a Worker.
Deleting a Worker
From the worker list, Delete removes a worker. Requires the delete_workers permission.
Deletion tears down the pipeline, the build project, the git repository, and the pm2 app, then removes the worker from the project.
Deleting a worker is irreversible, and it destroys the worker’s source repository. If the repository holds work that isn’t mirrored anywhere else, clone it first.
Deleting a worker does not affect the project’s RabbitMQ broker, sibling workers, or any data in DaaS. Messages already queued for the deleted worker’s job types stay in their queues with nothing consuming them.
Troubleshooting
Enablement stuck, then failed. Project enablement has a 15-minute deadline. Past that the project is marked Failed with a timeout reason. Retry is safe.
Worker sits at provisioning indefinitely. Worker creation has no automatic timeout, so
a long-stuck row is stuck rather than slow. Delete it and create a new one; contact support
if it recurs.
Build succeeds, process never runs. Check for an ecosystem.config.js whose app name
isn’t ${PROJECT_ID}-${WORKER_ID}. That combination fails silently — success everywhere,
nothing running. Removing the file is the fastest fix.
Process restarts in a loop. Your start script is exiting. A worker must stay running;
pm2 restarts anything that exits. Check the application logs for the error just before each
restart.
Configuration changes have no effect. Saving the environment file doesn’t restart the process. Restart the worker, or push a deploy.
Worker can’t reach RabbitMQ. Confirm the project enablement badge reads Active, then
check RABBITMQ_URL on the Environment page. If it’s empty, use Prefill recommended
values and save — a new worker’s environment file starts out empty.
Duplicate name rejected on a name you don’t see. Names are compared case-insensitively and ignore surrounding whitespace, and the check covers the whole project.