Skip to content

troubleshooting.md

Latest commit

 

History

History
121 lines (88 loc) · 4.36 KB

troubleshooting.md

File metadata and controls

121 lines (88 loc) · 4.36 KB

Troubleshooting

Common issues and how to resolve them.

Database connection errors

Symptoms: Snaapi fails to start, logs show "connection refused" or "no such host."

Solutions:

  • Verify your DATABASE_URL is correct. The format is postgres://user:password@host:port/dbname.
  • Make sure PostgreSQL is running. If using Docker Compose, check with docker compose ps.
  • If Snaapi runs in Docker and PostgreSQL runs on the host, use host.docker.internal instead of localhost in the connection string (macOS/Windows) or --network host (Linux).
  • Check that no firewall rules are blocking port 5432 between the Snaapi container and the database.

"Invalid install token"

Symptoms: The setup page at /install rejects your token.

Solutions:

  • Check that the SNAAPI_INSTALL_TOKEN environment variable is set and matches what you are entering.
  • If you did not set SNAAPI_INSTALL_TOKEN, Snaapi generates a random token at startup. Check the container logs with docker compose logs snaapi and look for a line containing the generated token.

403 Forbidden errors

Symptoms: API requests return 403 Forbidden even though you are authenticated.

Solutions:

  • Check the user's role and ensure the role has a permission entry for the resource and action you are calling. See Permissions.
  • If using an API key, verify the key's permissions object includes the resource and action. See API Keys.
  • Check that the resource itself is enabled (enabled: true in the resource settings).
  • If using an admin token for create or update operations, note that admin tokens are restricted to read and delete on resource endpoints. Use the dedicated admin endpoints instead. See Admin Token Restrictions.

Webhook delivery failures

Symptoms: Webhooks are not reaching your endpoint, or the delivery log shows errors.

Solutions:

  • Verify the webhook endpoint URL is reachable from the Snaapi server. If both run in Docker, use the container name or Docker network hostname instead of localhost.
  • Check that the webhook is enabled in the Admin Console.
  • Review delivery logs in the Admin Console under the webhook's detail page. Failed deliveries show the HTTP status code and response body from your endpoint.
  • Make sure your endpoint responds with a 2xx status code within the timeout period.

SSE connection drops

Symptoms: Real-time stream connections close unexpectedly or never receive events.

Solutions:

  • If you are behind a reverse proxy (Nginx, Caddy, etc.), increase the proxy timeout to at least 60 seconds. Snaapi sends a heartbeat every 30 seconds, so any timeout shorter than that will kill the connection.
  • For Nginx, set proxy_read_timeout 86400s; and proxy_buffering off; on the /stream location.
  • Check that your SNAAPI_TRUSTED_ORIGINS or CORS settings include the origin of your frontend application.

Password reset not working

Symptoms: Users request a password reset but never receive the email.

Solutions:

  • Snaapi does not include a built-in email provider. You must configure an external email service for password-reset emails to be delivered. Check your email provider settings in the environment configuration.
  • See Configuration for email-related environment variables.

Missing fields in API response

Symptoms: Some fields you defined on a resource do not appear in the API response.

Solutions:

  • Check the role's read permission for the resource. The fields array controls which fields are returned. If a field is not listed, it is excluded from the response. See Permissions.
  • If using an API key with scoped permissions, verify the key's permission object includes the missing fields.
  • System fields (id, created_at, updated_at) are always returned regardless of the fields list.

"Resource not found" for an existing resource

Symptoms: API calls to /v1/<name> return a 404 even though the resource exists in the Admin Console.

Solutions:

  • Check whether the resource is disabled. Resources with enabled: false do not expose API endpoints. Re-enable the resource in the Admin Console or via the admin API.
  • Double-check the resource name in the URL. Resource names are case-sensitive and must match exactly.
⚡