Troubleshooting

Start with php artisan wake:doctor in the reporting application, and the application's ingest health page in Wake. Between them they separate "the client never tried" from "Wake refused it" from "Wake accepted it and it is not in the lake yet".

The deploy fails on wake:lake-bootstrap

DuckDB is missing from the artifact. wake:lake-bootstrap shells out to bin/duckdb, which the build step wake:install-duckdb puts there, so check the build log for that step before anything else. A deployment created before Wake's catalog row carried the step was built without it and needs a fresh deploy from a row that has it.

Nothing arrives, and the application reports nothing wrong

This is the normal shape of a Wake problem, because the client swallows delivery failures by design so that a Wake outage cannot fail your requests.

The commonest cause is LOG_STACK. Installing the client adds a wake channel and nothing writes to it until the stack names it, so an application with WAKE_URL and WAKE_TOKEN set and LOG_STACK=single is configured correctly and still sends nothing.

The next commonest is a WAKE_URL with a path on it. The client appends /api/v1/ingest itself.

Run wake:doctor in the environment that should be reporting, not locally.

Every batch is refused with 403

The credential is valid and not allowed to ingest. Either the application record was deleted from Wake while the reporting application kept its credential, or the record exists and is disabled, or the credential belongs to a different application.

If you minted the credential through Scalpels rather than Wake's admin pages, this is the expected result: Wake resolves the credential's subject against its own connected-apps table, and a Scalpels-minted subject has no row there. Create the application in Wake and use the credential it shows you.

Batches are refused with 401

Absent, invalid, expired or revoked. A credential that was rotated stops working immediately, so a 401 right after a rotation means the reporting application still holds the old value.

429, repeatedly

The application has hit its batches-per-minute or events-per-minute cap. The response carries a Retry-After and the client honours it, keeping the same idempotency key, so nothing is lost unless the client's buffer fills while it waits. Either raise that application's caps or reduce what it logs. Configuration covers the caps.

Ingest health shows a growing drop count

The client is losing events before delivery: the buffer filled while Wake was unreachable or slow, or deliveries are timing out. The count is cumulative since the last accepted batch, so a number that keeps climbing means the problem is current and a number that stopped climbing means it has passed.

Accepted batches are not in search results

A 202 means the batch is durable in PostgreSQL staging. wake:lake-flush moves it into the lake, and it runs every minute from the schedule. A persistent lag means the scheduler is not running on the environment, or the flush is failing. Check the Cloud environment has the scheduler enabled, then run php artisan wake:lake-flush once by hand and read what it says.

Searches get slower every day

The daily compaction is not running. wake:lake-compact dispatches the per-day rewrite onto the managed queue, so this looks the same whether the schedule is off or the queue is not attached, not running workers, or not consuming the wake-lake queue. Confirm in the Laravel Cloud dashboard that the managed queue is attached to the Wake environment and its workers are running, and do not set QUEUE_CONNECTION yourself to fix it.

The lake writer says it is busy

One rewrite holds a PostgreSQL advisory lock while it runs so that two writers cannot touch the lake at once. A job that finds the lock taken fails and is retried, three times. Seeing this occasionally in failed jobs is the lock working. Seeing it constantly means something else is holding the lake open, which usually means a manual wake:lake-flush or wake:lake-compact left running.