Docs / Guides / Troubleshooting

Troubleshooting

This guide covers the most common problems people run into and how to resolve them. Start with the symptom that matches yours, then follow the steps. If nothing here fits, jump to Collecting logs before asking for help.

Quick checks

Before digging in, confirm the basics. Most issues are resolved by one of these:

Check that the service is running and listening on the expected port.
Confirm you are on the version the docs describe. Run --version to see what is installed.
Restart the process after changing any configuration file.
Look at the most recent entries in the log file, not the oldest.

$ app --version
app 3.4.1

$ app status
state:   running
listen:  0.0.0.0:8080
uptime:  2h 14m

Connection refused or timeouts

If clients cannot reach the service, the problem is usually one of three things: the process is not running, it is bound to a different address, or a firewall is in the way.

Symptom	Likely cause	What to do
`ECONNREFUSED`	Nothing is listening on that port	Check `app status` and confirm the port in your config.
`ETIMEDOUT`	Firewall or security group blocking traffic	Open the port for your client's IP range and retry.
`EADDRINUSE` in logs	Another process holds the port	Run `lsof -i :8080` and stop the other process, or change the port.
Works locally, not remotely	Bound to `127.0.0.1`	Set `listen_address` to `0.0.0.0` or a specific interface.

Authentication failures

A 401 Unauthorized or 403 Forbidden response almost always means the credentials are missing, expired, or scoped too narrowly.

Confirm the token is present in the Authorization header with the Bearer prefix.
Check the token has not expired. Tokens are valid for 24 hours by default.
Verify the token's scope includes the action you are attempting.

Note: Tokens are shown only once when created. If you have lost one, generate a new token and revoke the old one.

Slow responses

When requests take longer than expected, look at these in order:

Connection pool size. If every connection is busy, requests queue. Raise pool.max_connections cautiously; the database may become the bottleneck.
Cache hit rate. A cold or disabled cache sends every request to the backend. Enable cache.enabled and watch the hit ratio.
Large payloads. Paginate list endpoints with ?limit= and ?cursor= rather than fetching everything at once.

Collecting logs

If you need to open a support request, include the output of the diagnostic command. It gathers the configuration (with secrets redacted), recent logs, and version information in one file.

$ app diagnose --since 1h --output app-diag.tar.gz

To increase log detail temporarily, set the level to debug. Remember to switch it back, since debug logging is verbose and can fill disks quickly.

log:
  level: debug   # default: info

Still stuck?

Search the error code reference for the exact message you are seeing. If that does not help, open an issue on the project tracker and attach the diagnostic bundle from the previous section. Include the version, your operating system, and the exact steps that led to the problem.