Docs Self-hosting
Troubleshooting
Find and correct the common problems of a self-hosted Snapsbrew instance.
Where to look first
| Source | How to read it |
|---|---|
| The app log (Docker) | docker compose logs web horizon scheduler. The Docker image sets LOG_CHANNEL=stderr. |
| The app log (no Docker) | The daily files in storage/logs/. |
| Failed jobs | The Horizon dashboard at /horizon, as the owner. |
| One API request | The X-Request-Uuid header of a snap, batch or embedded form response. It is the uuid of the usage log row. Open /logs/<uuid> to read the row. |
| The usage log | /logs in the app. |
Install and start
docker compose stops with "Set DB_PASSWORD in .env"
A required variable is empty. Set DB_PASSWORD, DB_ROOT_PASSWORD and BROWSERLESS_TOKEN in .env. Read Install with Docker.
The web container is not healthy
The first start runs all the migrations. The health check waits up to 10 minutes. If the container is still not healthy after that time, read its log:
docker compose logs web
The setup page returns 404
An account exists, so the setup page is closed. Sign in with that account. If you lost its password, read Recover access.
"The setup token is not correct"
The token comes from APP_KEY. If APP_KEY changed after you copied the URL, the old token does not work. Show the current URL:
php artisan snapsbrew:setup-url
Renders
Snaps stay pending
The queue worker does not run.
- If
QUEUE_CONNECTIONisredis, make sure that Horizon runs. With Docker, readdocker compose ps. - Make sure that
APP_ENVisproductionorlocal. With another value, Horizon starts no worker. - Open
/horizonand look for failed jobs.
Read Queues and Horizon.
A snap has the status failed
Read last_error of the snap. It holds the error of the renderer.
If the log has "browserless screenshot render failed after 3 attempts":
-
Make sure that Browserless runs:
docker compose ps browserless. -
Make sure that
BROWSERLESS_URLandBROWSERLESS_TOKENare correct. -
From the app host, send a test request to Browserless:
curl "http://127.0.0.1:3000/json/version?token=<token>"
Images or fonts are empty in the render
The renderer cannot load the image or the font from its URL. This is the most frequent problem with Browserless.
- If
APP_URLis alocalhostURL, Browserless cannot reach the files of thepublicdisk. Use a public domain, a bucket, orRENDER_DRIVER=browsershot. - If the media URL uses a self-signed certificate, Chrome does not trust it.
- If the server blocks outgoing traffic, Chrome cannot reach
fonts.googleapis.com.
Read Rendering.
Browsershot cannot find Chrome
Puppeteer did not download a Chrome, or Node is not at the configured path.
- Set
BROWSERSHOT_NODE_PATHandBROWSERSHOT_NPM_PATHto the correct binaries. - Set the Puppeteer variable
PUPPETEER_EXECUTABLE_PATHto the path of a local Chrome.
A template edit does not show in new snaps
Snaps render the published version of the template. Publish the template after the edit. Read Templates.
The API returns 422 for a webhook_url or an image_url
The URL must be http or https, and its host must resolve to public addresses. The app refuses private, loopback and link-local hosts. The host of APP_URL is accepted. Read Security.
Signed URLs and embedded forms
A signed URL shows a placeholder image
The app shows the placeholder image instead of an error when:
- the signature is missing or wrong,
- the signed-URL key was deleted,
- the template does not exist,
- the owner of the template is deactivated.
Make sure that you sign the sorted parameters with the correct key. Read Signed URLs.
A signed URL returns 400 "Invalid variants payload."
The variants value is not valid after the app decodes it. Make sure that it is the base64 of a JSON array of variants.
An embedded form returns 404
- The signature in the URL changed. Use the exact URL that the form page gives.
- The instance moved to a new host. Add the old host to
APP_PREVIOUS_URLS. - The owner of the form is deactivated.
An embedded form does not load in an iframe
A proxy adds X-Frame-Options or a frame-ancestors rule. Read Reverse proxy and TLS.
Web app and links
Links and signed URLs start with http:// behind HTTPS
The app does not trust the proxy headers. Set TRUSTED_PROXIES=* and make sure that the proxy sends X-Forwarded-Proto.
Invitation and password emails do not arrive
MAIL_MAILER=log writes each email to the log and sends nothing. Configure a mailer, or use the commands in Recover access.
/horizon or /admin returns 404 or 403
Only the owner can open these pages. Sign in as the owner, or make a user the owner with php artisan snapsbrew:install --promote=<email>.
API and MCP
The API returns 429
The request went over a rate limit. Wait for the time in the Retry-After header. Read API overview.
/mcp returns 404
MCP_ENABLED is false. Set it to true and restart the app.
The OAuth connection of an MCP client fails at the consent step
The redirect host of the client is not in MCP_REDIRECT_DOMAINS. Add the scheme and the host of the client, or use an API token. Read OAuth.