Troubleshooting
Account and permissions
| Problem | What to check |
|---|---|
| Cannot sign in | Verify email, use the newest verification link, check password and account ban status |
| Email never arrives | Check spam, configured provider/sender, credentials, outbound connectivity, and operator logs |
| Setup unavailable | An administrator may already exist, or SETUP_TOKEN may be missing/invalid; use existing-account recovery rather than deleting data |
| Missing content | Clear filters, check language/Trash, and ask an administrator to inspect effective content access |
| Missing action | Check both role and content edit permissions, current workflow status, and whether the type requires approval |
| Approval denied | A different person must approve the author's revision in strict workflow |
See account access and users and permissions.
Editing and publication
| Problem | What to check |
|---|---|
| Draft is not live | Saving does not publish; complete the required review and publication |
| Save failed | Keep the editor open, check connectivity, and retry after reconciling any concurrent changes |
| Stale/conflict response | Refresh entry, policy, or release state before confirming again; do not blindly retry |
| Publication rejected | Check required fields, references, enabled language, latest revision, and current-policy approval |
| Website unchanged | Inspect published delivery for the intended language, then the consuming application's fetching and cache |
| Schedule did not run | Check backend uptime, job mode/cron, due time/timezone, captured revision, permissions, and failed/expired state |
| Webhook failed | Check encryption key, public HTTPS destination, receiver status, and delivery attempts; publication may already have succeeded |
Read workflow and jobs before changing publication state.
Uploads and production startup
| Problem | What to check |
|---|---|
| Upload rejected | Category enabled, supported format, per-file/request limits, scanner status, and available disk space |
| HTTP 413 | Both Nginx client_max_body_size and backend upload/request limits |
| Audio/video fails at startup | ffprobe for audio/video, plus ffmpeg for video, reachable by the service user |
| Production email configuration error | Real Resend values or valid SMTP settings; production requires configured email |
| Missing environment | The production start script does not load .env; inspect EnvironmentFile or explicit env-file loading |
| JSON validation error | Supply a complete configuration, valid field names, and valid values rather than a partial snippet |
| Database/table error | Correct database URL and reviewed migrations applied while writers are stopped |
| Nginx 502 | Backend process, loopback port, service logs, and upstream reachability |
| Nested browser route fails | Production frontend exists at paths.frontendDist, NODE_ENV=production, and proxy passes application routes |
| Email links use localhost | Set both public URL variables to the actual production HTTPS origin and restart |
For the production layout:
sh
sudo systemctl status tinycms
sudo journalctl -u tinycms -n 100 --no-pager
curl --fail http://127.0.0.1:3000/health
sudo nginx -tLogs can contain sensitive operational details. Share only the relevant redacted error, time, and release identity.
Backup and restore
| Problem | What to check |
|---|---|
| Deployment lock held | Stop every writer and restart mechanism, then wait for graceful exit |
| Apparently stale lock | Inspect owner.json and confirm all writers are stopped before removing the exact lock; PID absence alone is insufficient |
| Backup path rejected | Private, non-overlapping paths; no public roots, symlinks, hardlinks, or special files |
| Missing referenced file | Investigate missing originals/profile images; a database-only snapshot does not fix missing media |
| Incompatible bundle | Use the exact matching release and build metadata; do not edit checksums or force compatibility |
| Restore destination rejected | Use a new empty destination outside protected data and backup storage |
| Restored login or webhooks fail | Recover original auth secret and encryption key separately; never invent replacements as a recovery shortcut |
| Interrupted bundle | .partial-* is incomplete and cannot be restored |
Follow backups and recovery for the full procedure. Stop before destructive retries and preserve the failed state for investigation.