Troubleshooting
bunway is not found
Run through Bun (bunx bunway help) or install @bunway/cli globally. Confirm Bun's global bin path is
on PATH.
Database connection or migration fails
Check .env, run bunway db:list, and ensure the selected server exists. Use
bunway db:migrate --database=name; --all stops at the first failure and is not a distributed
transaction.
Generator says a file exists
Generators intentionally do not overwrite application code. Rename/remove the collision only after reviewing it, or edit the existing source manually.
Worker does not process jobs
Check the startup banner for the active driver. postgres requires migrations so bunway_jobs exists;
memory means no jobs database URL was found, so enqueued work only exists inside that one process.
Import every definition from src/jobs/index.ts, and verify BUNWAY_JOBS_DATABASE selects the
intended database. If QUEUES is set, it must include the enqueued queue.
SSE is connected but does not update
Disable reverse-proxy buffering. The publisher and connection must currently be in the same Bun process. The same constraint applies to Job progress emitted from a separate worker.
WebSocket does not connect
Forward HTTP/1.1 upgrade headers, use wss: behind HTTPS, and confirm the channel query value. Bunway's
browser helper does not add automatic WebSocket reconnection in v0.1.
OAuth provider is missing or callback mismatches
Set both provider credentials, restart the API, and register the exact
<BETTER_AUTH_URL>/api/auth/callback/<provider> URL. Development disables providers with missing values.
Mail/SMS stays in the console
That is the safe development default. Set a supported driver and all required provider variables.
Production never permits console delivery. sendLater() additionally requires migrations and a worker.
Upload is saved but inaccessible
Check STORAGE_PUBLIC_URL, the /storage route, filesystem permissions, and proxy upload size. For S3,
verify endpoint, region, bucket credentials, and that the public URL can actually serve the object.
Set DEBUG=1 only when a CLI failure needs its unexpected stack trace; ordinary user errors are concise.