Common Issues & Solutions
Match the symptom to a binding, a Servit outcome, or the dead-letter channel.
| Symptom | Likely cause | Where to look | Fix |
|---|---|---|---|
| Message never arrives | URI or channel name does not match | deploy source and service.xml channel-name | Align ${param:name} with message parameters |
| Step stops | ServitException | dead-letter URI with messageId | Repair the unfinished step or the missing resource |
| Business decline | Expected outcome | rejected outbound channel | Read UserErrorCode. Do not treat it as a platform crash |
init fails | Resource ref is missing | service.xml ref-name and deploy resource type | Declare both before the node starts |
New folder has context/ and routes/ | pocat init --dir | scaffolded tree | Use the deployment root instead |
Platform ErrorCode bases include 400000 InvalidMessage, 401000 Unauthorized, 403000 Forbidden, 404000 NotFound, 405000 NotAllowed, 409000 Conflict, 415000 UnsupportedType, 500000 UNKNOWN, 503000 UNAVAILABLE, and 504000 TIMEOUT. A UserErrorCode adds a subcode from 1 to 999.