Troubleshooting
Start with the symptom, check the named input, and verify the result after each change.
The app exits during startup
Likely cause: runtime validation rejected a value.
Read the first error line. It names the variable and accepted shape. Common causes are a short session password, an invalid origin, or an invalid Sentry value.
Health returns 503
Likely cause: Masir cannot query Postgres.
Check the database health, connection URL, network, credentials, and Postgres 18 version. In Compose, also check the db service log.
Sign-in returns to the login page
Likely cause: the browser did not send the session cookie.
Confirm HTTPS and NUXT_SESSION_COOKIE_SECURE=true. On private plain HTTP, set it to false. Also confirm that the public origin matches the address in the browser.
A signed-in user sees no access
Likely cause: the user is not a member of the workspace.
The owner invites the user from the members page. Open the invite link and sign in with the invited email address.
Country is empty
Likely cause: no trusted country header reaches Masir.
Set NUXT_GEO_COUNTRY_HEADER to the header written by your CDN or proxy. Inspect a request at the app and confirm the proxy removes any client-supplied copy first.
Many users share one rate limit
Likely cause: Masir sees the proxy address as the client.
Set NUXT_TRUSTED_PROXY_DEPTH to the exact number of trusted proxies. Do not increase it beyond the real chain.
Rate limits differ between instances
Likely cause: each process uses its own memory counters.
Set NUXT_REDIS_URL to a shared rediss:// endpoint.
Postgres reports too many clients
Likely cause: pool size multiplied by instance count exceeds the database limit.
Lower NUXT_DATABASE_POOL_MAX, reduce instances, or use a pooler.
Invitation or recovery mail does not arrive
Likely cause: no mail provider is active or the provider rejected the message.
Check the startup line that names the selected mail driver. Review SMTP or Resend credentials, sender authorization, and application logs. With no provider, Masir writes the message to the log.
A link exists but returns 404
Check the link prefix, slug, enabled state, schedule, expiry, visit limit, and deletion state. An unavailable link can also show the generic unavailable page instead of revealing its state.
One instance serves an old destination
Likely cause: an instance has stale in-memory link cache data or traffic is reaching deployments with different databases.
Confirm all instances use the same Postgres database and version. Restart the stale instance. Link writes invalidate the cache by link ID and slug.
The app cannot store a logo
Check the selected storage provider and upload limit. File storage needs a writable durable volume. Multi-instance deployments should use S3-compatible storage.
Continue diagnosis
Collect the Masir version, deployment shape, first relevant log line, health response, and the configuration names involved. Remove all secret values before sharing logs.
Read moreReview the security boundaries