Security and troubleshooting
Diagnose common authentication, batch, file, rule, token, and deployment failures safely.
Use this page to identify the smallest safe diagnostic for a failed request and verify recovery. Collect redacted logs, status codes, and request context; never publish passwords, tokens, or protected-file URLs.
Before you begin
You need access to PocketBase logs and the client that made the failing request. For deployment failures, identify the environment and exact PocketBase version. Reproduce with synthetic data where possible.
Authentication fails with “Failed to authenticate.”
PocketBase returns this message when the auth record is missing or the password does not validate. Password authentication also requires the selected identity field to have a unique index.
- Confirm that the request targets the intended auth collection and includes
identityandpassword. - Confirm that the identity field is enabled for password authentication and has a single-column unique index.
- Retry with a known test account and record only the status and response message.
A batch request is interrupted or times out
The batch processor can report batch request interrupted when the request context ends, or batch transaction timeout when processing exceeds its timeout. An unknown action also fails the batch.
- Confirm whether the client cancelled the request, the connection closed, or the server reported a timeout.
- Identify the first failed operation and check whether it is safe to repeat.
- Retry only unresolved work with a smaller batch and an appropriate client timeout.
Rules, files, or tokens return unauthorized responses
Check authenticated state first, then the collection API rule for the exact operation. For a protected file, confirm authentication and request a file token through the supported SDK or API flow. Do not make data public as a diagnostic shortcut.
Record the status, collection operation, record identifier, and auth state. Review the rule with a non-sensitive test record, then rerun with the least-privileged test account.
Deployment or rate-limit failures persist
Compare the failing environment with the working one: PocketBase version, configuration, storage, reverse-proxy timeouts, and request rate. Keep rate limits enabled. Capture timestamps without authorization headers.
Escalate safely
Provide redacted method and path, status, error text, version, relevant configuration names, and a minimal reproduction. Include reproducibility and the first failing batch index when applicable.
Next steps
Review API rules and filters, realtime subscriptions, and Deploy PocketBase to production.