Skip to content

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.

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.

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

Open source link management for teams. Released under the MIT License.