[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74QR2Y4F9FDKHKA53D5CGCF":3,"skill-same:01M74QR2Y4F9FDKHKA53D5CGCF":66},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":40,"commitSha":41,"skillDirectory":42,"forksCount":13,"repositoryHtmlUrl":43,"repositoryHomepageUrl":6,"ownerHtmlUrl":44,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":45,"install":46,"resources":59},"01M74QR2Y4F9FDKHKA53D5CGCF","self-hosted-social-scheduler",null,"Postiz\u002Fself-hosted social: Docker+DB+API debugging.","LyrikNilpferd71\u002FHermes-Backup","LyrikNilpferd71","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F187173780?v=4","01M727S8GPB77P0S9ECRRMZT58","01M727S8HF63B0MD53F496MK1V",0,"MIT","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-09-27T14-00-39+0200\u002Fskills\u002Fdevops\u002Fself-hosted-social-scheduler\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: self-hosted-social-scheduler\ndescription: \"Postiz\u002Fself-hosted social: Docker+DB+API debugging.\"\nversion: 1.0.0\nauthor: Hermes Agent\nlicense: MIT\nplatforms: [linux]\nmetadata:\n  hermes:\n    tags: [postiz, social-media, docker, postgresql, debugging, instagram, tiktok, oauth]\n    related_skills: [systematic-debugging]\n---\n\n# Self-Hosted Social Scheduler Debugging\n\n## Overview\n\nDiagnose posting failures on self-hosted social media schedulers (Postiz, Buffer, etc.) that run in Docker with PostgreSQL. The canonical flow is:\n\n1. **Confirm** the service is running and healthy  \n2. **Inspect config** (docker-compose for API keys, tokens)  \n3. **Check container logs** for upstream timeouts and social API errors  \n4. **Query the DB directly** for post state, error messages, and integration status  \n5. **Interpret social API error codes**  \n\nAlways do these **before** suggesting the user re-authenticate — the DB tells the real story.\n\n---\n\n## Step 1: Service Health\n\n```bash\ndocker ps --format \"table {{.ID}}\\t{{.Names}}\\t{{.Ports}}\\t{{.Status}}\" | grep postiz\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\" http:\u002F\u002Flocalhost:4007\n```\n\nA 307 redirect is normal (SSR app). A 200 or 502 tells you backend status.\n\n---\n\n## Step 2: Configuration Inspection\n\n```bash\nread_file \u002Fopt\u002Fpostiz\u002Fdocker-compose.yaml\n```\n\nKey env vars: `MAIN_URL`, `FRONTEND_URL`, `INSTAGRAM_APP_ID\u002FSECRET`, `TIKTOK_CLIENT_ID\u002FSECRET`, `JWT_SECRET`, `NOT_SECURED`.\n\n---\n\n## Step 3: Container Logs\n\n```bash\n# Get recent errors (filter \u002Fapi\u002Fmcp scanner noise)\ndocker logs --tail 100 postiz 2>&1 | grep -iv \"upstream timed out\" | grep -iE \"error|fail|instagram|tiktok|facebook|oauth|token\"\n```\n\n---\n\n## Step 4: Database Introspection\n\n### Connect\n\n```bash\ncat \u003C\u003C 'SQL' | docker exec -i postiz-postgres sh -c 'psql -U postiz-user -d postiz-db-local'\n-- SQL here\nSQL\n```\n\nFor multi-line queries, write a temp file inside the container to avoid shell quoting issues:\n\n```bash\ndocker exec postiz-postgres sh -c \"cat > \u002Ftmp\u002Fq.sql \u003C\u003C 'SQL'\nSELECT ... FROM \\\"Table\\\";\nSQL\npsql -U postiz-user -d postiz-db-local -f \u002Ftmp\u002Fq.sql\"\n```\n\n### Discover columns first — Postiz uses **camelCase**\n\n```sql\nSELECT column_name, data_type FROM information_schema.columns\nWHERE table_name = 'Post' ORDER BY ordinal_position;\n```\n\n### Key Tables\n\n**User:**\n```sql\nSELECT id, email, name, \"createdAt\" FROM \"User\" ORDER BY \"createdAt\" DESC;\n```\n\n**Integration (connected social accounts):**\n```sql\nSELECT id, name, type, profile, \"providerIdentifier\", \"refreshNeeded\"\nFROM \"Integration\" ORDER BY \"createdAt\" DESC;\n```\n- `providerIdentifier` = platform (`instagram-standalone`, `tiktok`, `facebook`, `x`)\n- `refreshNeeded` = `true` means token expired, needs re-auth\n\n**Post (scheduled\u002Fpublished\u002Ffailed):**\n```sql\nSELECT id, title, state, \"publishDate\", \"integrationId\"\nFROM \"Post\" ORDER BY \"publishDate\" DESC NULLS LAST LIMIT 20;\n```\n- `state`: `QUEUE` = scheduled, `PUBLISHED` = done, `ERROR` = failed, `DRAFT` = draft\n- Join on `integrationId` to get platform\n\n**Errors (JSON failure traces):**\n```sql\nSELECT id, message, \"createdAt\" FROM \"Errors\" ORDER BY \"createdAt\" DESC LIMIT 5;\n```\nThe `message` column is a JSON blob from Temporal. Parse `details[0].json` for the actual API error payload.\n\n### Cross-reference posts with platforms\n\n```sql\nSELECT p.id, p.title, p.state, p.\"publishDate\", i.\"providerIdentifier\"\nFROM \"Post\" p\nLEFT JOIN \"Integration\" i ON p.\"integrationId\" = i.id\nORDER BY p.\"publishDate\" DESC NULLS LAST;\n```\n\n---\n\n## Step 5: Social API Error Patterns\n\n### Instagram \u002F Facebook — \"API access blocked\" (OAuthException code 200)\n\n**Meaning:** Meta revoked\u002Fblocked the access token. Common causes:\n- Token expired (60-day lifetime for Instagram)\n- Password changed → all tokens invalidated\n- App disconnected from Instagram Settings\n- Instagram professional account status changed\n\n**Fix:** Re-authenticate in Postiz UI (Integrations → Instagram → Disconnect & Reconnect).\n\n**Quirk:** Earlier queued posts may show `PUBLISHED` while later ones fail — the token was valid when queued, then expired.\n\n### TikTok — \"App not approved for public posting\"\n\n**Error:** `unaudited_client_can_only_post_to_private_accounts`\n\n**Meaning:** The TikTok developer app hasn't passed TikTok's audit. Unaudited apps can only post to private\u002Fself-view accounts.\n\n**Fix:** Submit the app for review in TikTok Developer Portal. Not fixable in Postiz config.\n\n### TikTok — \"url_ownership_unverified\"\n\n**Error:** `PULL_FROM_URL` rejected by TikTok's API.\n\n**Meaning:** TikTok does not support URL-based media transfer for unaudited apps. The image bytes must be uploaded directly.\n\n**Fix:** Use DIRECT_POST instead of PULL_FROM_URL, or wait for TikTok app audit.\n\n### Upstream Timeouts (Nginx → Backend)\n\n**Log:** `upstream timed out (110: Connection timed out)`\n\n**Meaning:** Node.js backend (port 3000) hung. Often from slow third-party API calls or DB query issues.\n\n**Diagnosis:**\n```bash\ndocker logs postiz 2>&1 | grep -v \"upstream timed out\" | grep -v \"\u002Fapi\u002Fmcp\"\n```\n\n---\n\n## Pitfalls\n\n- **`column does not exist`:** Postiz uses camelCase. Always quote: `\"createdAt\"` not `created_at`. When piping through bash, heredoc with `'END'` (single-quoted delimiter) works.\n- **Docker logs are noisy:** Scanners hit `\u002Fapi\u002Fmcp`. Always filter them out.\n- **Token ≠ App keys:** The `docker-compose.yaml` shows app Client ID\u002FSecret, not user tokens. User tokens are in the DB `Integration.token`\u002F`refreshToken`.\n- **\"Instagram worked for some posts, not others\":** Token was valid when those were queued. Check error timestamps vs post creation times.\n- **Psql inside docker exec:** `cat | docker exec -i postgres sh -c 'psql ...'` is reliable. For complex queries, write to a temp file first.","# Self-Hosted Social Scheduler Debugging\n\n## Overview\n\nDiagnose posting failures on self-hosted social media schedulers (Postiz, Buffer, etc.) that run in Docker with PostgreSQL. The canonical flow is:\n\n1. **Confirm** the service is running and healthy  \n2. **Inspect config** (docker-compose for API keys, tokens)  \n3. **Check container logs** for upstream timeouts and social API errors  \n4. **Query the DB directly** for post state, error messages, and integration status  \n5. **Interpret social API error codes**  \n\nAlways do these **before** suggesting the user re-authenticate — the DB tells the real story.\n\n---\n\n## Step 1: Service Health\n\n```bash\ndocker ps --format \"table {{.ID}}\\t{{.Names}}\\t{{.Ports}}\\t{{.Status}}\" | grep postiz\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\" http:\u002F\u002Flocalhost:4007\n```\n\nA 307 redirect is normal (SSR app). A 200 or 502 tells you backend status.\n\n---\n\n## Step 2: Configuration Inspection\n\n```bash\nread_file \u002Fopt\u002Fpostiz\u002Fdocker-compose.yaml\n```\n\nKey env vars: `MAIN_URL`, `FRONTEND_URL`, `INSTAGRAM_APP_ID\u002FSECRET`, `TIKTOK_CLIENT_ID\u002FSECRET`, `JWT_SECRET`, `NOT_SECURED`.\n\n---\n\n## Step 3: Container Logs\n\n```bash\n# Get recent errors (filter \u002Fapi\u002Fmcp scanner noise)\ndocker logs --tail 100 postiz 2>&1 | grep -iv \"upstream timed out\" | grep -iE \"error|fail|instagram|tiktok|facebook|oauth|token\"\n```\n\n---\n\n## Step 4: Database Introspection\n\n### Connect\n\n```bash\ncat \u003C\u003C 'SQL' | docker exec -i postiz-postgres sh -c 'psql -U postiz-user -d postiz-db-local'\n-- SQL here\nSQL\n```\n\nFor multi-line queries, write a temp file inside the container to avoid shell quoting issues:\n\n```bash\ndocker exec postiz-postgres sh -c \"cat > \u002Ftmp\u002Fq.sql \u003C\u003C 'SQL'\nSELECT ... FROM \\\"Table\\\";\nSQL\npsql -U postiz-user -d postiz-db-local -f \u002Ftmp\u002Fq.sql\"\n```\n\n### Discover columns first — Postiz uses **camelCase**\n\n```sql\nSELECT column_name, data_type FROM information_schema.columns\nWHERE table_name = 'Post' ORDER BY ordinal_position;\n```\n\n### Key Tables\n\n**User:**\n```sql\nSELECT id, email, name, \"createdAt\" FROM \"User\" ORDER BY \"createdAt\" DESC;\n```\n\n**Integration (connected social accounts):**\n```sql\nSELECT id, name, type, profile, \"providerIdentifier\", \"refreshNeeded\"\nFROM \"Integration\" ORDER BY \"createdAt\" DESC;\n```\n- `providerIdentifier` = platform (`instagram-standalone`, `tiktok`, `facebook`, `x`)\n- `refreshNeeded` = `true` means token expired, needs re-auth\n\n**Post (scheduled\u002Fpublished\u002Ffailed):**\n```sql\nSELECT id, title, state, \"publishDate\", \"integrationId\"\nFROM \"Post\" ORDER BY \"publishDate\" DESC NULLS LAST LIMIT 20;\n```\n- `state`: `QUEUE` = scheduled, `PUBLISHED` = done, `ERROR` = failed, `DRAFT` = draft\n- Join on `integrationId` to get platform\n\n**Errors (JSON failure traces):**\n```sql\nSELECT id, message, \"createdAt\" FROM \"Errors\" ORDER BY \"createdAt\" DESC LIMIT 5;\n```\nThe `message` column is a JSON blob from Temporal. Parse `details[0].json` for the actual API error payload.\n\n### Cross-reference posts with platforms\n\n```sql\nSELECT p.id, p.title, p.state, p.\"publishDate\", i.\"providerIdentifier\"\nFROM \"Post\" p\nLEFT JOIN \"Integration\" i ON p.\"integrationId\" = i.id\nORDER BY p.\"publishDate\" DESC NULLS LAST;\n```\n\n---\n\n## Step 5: Social API Error Patterns\n\n### Instagram \u002F Facebook — \"API access blocked\" (OAuthException code 200)\n\n**Meaning:** Meta revoked\u002Fblocked the access token. Common causes:\n- Token expired (60-day lifetime for Instagram)\n- Password changed → all tokens invalidated\n- App disconnected from Instagram Settings\n- Instagram professional account status changed\n\n**Fix:** Re-authenticate in Postiz UI (Integrations → Instagram → Disconnect & Reconnect).\n\n**Quirk:** Earlier queued posts may show `PUBLISHED` while later ones fail — the token was valid when queued, then expired.\n\n### TikTok — \"App not approved for public posting\"\n\n**Error:** `unaudited_client_can_only_post_to_private_accounts`\n\n**Meaning:** The TikTok developer app hasn't passed TikTok's audit. Unaudited apps can only post to private\u002Fself-view accounts.\n\n**Fix:** Submit the app for review in TikTok Developer Portal. Not fixable in Postiz config.\n\n### TikTok — \"url_ownership_unverified\"\n\n**Error:** `PULL_FROM_URL` rejected by TikTok's API.\n\n**Meaning:** TikTok does not support URL-based media transfer for unaudited apps. The image bytes must be uploaded directly.\n\n**Fix:** Use DIRECT_POST instead of PULL_FROM_URL, or wait for TikTok app audit.\n\n### Upstream Timeouts (Nginx → Backend)\n\n**Log:** `upstream timed out (110: Connection timed out)`\n\n**Meaning:** Node.js backend (port 3000) hung. Often from slow third-party API calls or DB query issues.\n\n**Diagnosis:**\n```bash\ndocker logs postiz 2>&1 | grep -v \"upstream timed out\" | grep -v \"\u002Fapi\u002Fmcp\"\n```\n\n---\n\n## Pitfalls\n\n- **`column does not exist`:** Postiz uses camelCase. Always quote: `\"createdAt\"` not `created_at`. When piping through bash, heredoc with `'END'` (single-quoted delimiter) works.\n- **Docker logs are noisy:** Scanners hit `\u002Fapi\u002Fmcp`. Always filter them out.\n- **Token ≠ App keys:** The `docker-compose.yaml` shows app Client ID\u002FSecret, not user tokens. User tokens are in the DB `Integration.token`\u002F`refreshToken`.\n- **\"Instagram worked for some posts, not others\":** Token was valid when those were queued. Check error timestamps vs post creation times.\n- **Psql inside docker exec:** `cat | docker exec -i postgres sh -c 'psql ...'` is reliable. For complex queries, write to a temp file first.",{"name":5,"author":23,"license":14,"version":24,"metadata":25,"platforms":38,"description":7},"Hermes Agent","1.0.0",{"hermes":26},{"tags":27,"related_skills":36},[28,29,30,31,32,33,34,35],"postiz","social-media","docker","postgresql","debugging","instagram","tiktok","oauth",[37],"systematic-debugging",[39],"linux","main","404fd33aabef3b6bc1cc913117ba2160ade62625","snapshots\u002F2026-09-27T14-00-39+0200\u002Fskills\u002Fdevops\u002Fself-hosted-social-scheduler","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71","2026-11-08 20:00:57",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add LyrikNilpferd71\u002FHermes-Backup --skill self-hosted-social-scheduler",{"tool":52,"command":53},"bunx","bunx skills add LyrikNilpferd71\u002FHermes-Backup --skill self-hosted-social-scheduler",{"tool":55,"command":56},"pnpm","pnpm dlx skills add LyrikNilpferd71\u002FHermes-Backup --skill self-hosted-social-scheduler","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-09-27T14-00-39+0200\u002Fskills\u002Fdevops\u002Fself-hosted-social-scheduler\u002FSKILL.md",true,[60],{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fpostiz-debug-20260922.md","REFERENCE","参考文档",2538,"https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-09-27T14-00-39+0200\u002Fskills\u002Fdevops\u002Fself-hosted-social-scheduler\u002Freferences\u002Fpostiz-debug-20260922.md",[67,74,80,87,94,101],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M76BBCCNA7WQ82Q8QNZH8PBK","writing-plans","Write implementation plans: bite-sized tasks, paths, code.","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":75,"name":37,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M76BB8YS41CA3NKW0YMSSB88","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M76BB680FPNT998E1GM2QW10","subagent-driven-development","Execute plans via delegate_task subagents (2-stage review).","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fsubagent-driven-development\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M76BB3C4ZB9S4RWPMM8MX0YB","plan","Write a markdown plan to .hermes\u002Fplans\u002F; no execution.","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fplan\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":18},"01M76BB0NK28KMP51YDB5R3EXA","hermes-agent-skill-authoring","Author in-repo SKILL.md files: frontmatter and structure.","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fhermes-agent-skill-authoring\u002FSKILL.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":18},"01M76BAYV58H0CKNSTZE3ZH4NY","debugging-hermes-tui-commands","Debug Hermes TUI slash commands: Python, gateway, Ink UI.","https:\u002F\u002Fgithub.com\u002FLyrikNilpferd71\u002FHermes-Backup\u002Fblob\u002Fmain\u002Fsnapshots\u002F2026-11-08T13-00-51+0100\u002Fskills\u002Fsoftware-development\u002Fdebugging-hermes-tui-commands\u002FSKILL.md",[],[]]