Hub shows 502 on /api; backend crash-loops | The scheduler (Temporal) isn't reachable | Ensure the temporal container is up; it must start before Postiz settles. |
| Login bounces back to sign-in | Accessed over plain http | Always use https://postiz.wholetech.com — the cookie needs HTTPS. |
| Portal returns "database is locked" / 502 | Two connections writing at once | Already fixed: state is committed before the audit log writes. Don't re-introduce a second open connection mid-write. |
| New subfolder 301-redirect loops | Missing nginx location for the path | Add an explicit location ^~ /path/ block. |
| Files copied but site 404s | Permissions after a recursive copy | chmod -R a+rX the copied directory. |
| Facebook: “Could not add provider” or 409 “Page not found in your accounts” | The Meta app secret was truncated when copied | The secret is 32 hex characters — count them. A token exchange replying “Error validating client secret” confirms it. |
| Facebook: “Invalid Scopes” | Permission not added to the app's Pages use case | Meta app console → Use cases → Pages → add each permission explicitly. |
| Facebook: “domain isn't included in the app's domains” | App Domains field empty, or typed text never became a chip | Add postiz.wholetech.com and click the dropdown suggestion so it saves as a chip. |
| Facebook authorization fails for a second account | App is in Development mode; only app roles may authorize | Add that account as a Tester under App roles, and accept the invite. |
| “Why won't it post to my personal Facebook profile?” | Not a bug — Meta provides no API for personal profiles | Nothing to fix. Automate a Page; profiles must be posted by hand. See Facebook. |
| A network is connected but nothing ever posts to it | Connected is not the same as publishing. Each network needs a publisher function in publish_due.py; a channel with no publisher is silently skipped | Look for (channel <name> not wired yet) in the log. Adding the channel to a tenant is not enough on its own. |
| A Page reports no linked Instagram account, but you know there is one | The token lacks instagram_basic, so the API omits the field instead of erroring | Re-authorize with that permission, then check again. See Instagram. |
| Instagram posts fail every time | The post is text-only | Not fixable by configuration — Instagram requires an image or video on every post. Keep Instagram out of the channel list until an image pipeline exists. |
| Posts stopped going to X | Daily cost cap reached, or X credit empty | Expected if capped; otherwise top up X credit. Bluesky keeps posting. |
| Feed looks stale | Nightly feed build didn't run/ship | Check /var/log/social-feed.log; re-run gen-social-feed.py. |