Troubleshooting

For limits that apply to a single network, see Known issues.

#A post failed

Open the post. Each channel shows its own status and the error the network returned. You also get a notification, in the app and by email, that says "A post failed on {channel}" with the reason.

1. Read the error. It usually names the problem, for example "Too long for X" or "Choose a Pinterest board."
2. Fix the post, then click Retry failed. Postline publishes the failed channels again right away. Channels that already published aren't posted again.

Postline retries temporary errors on its own (the network can't be reached, it rate-limits you, or it has a server error). It tries up to 3 times in total, waiting about 1 minute and then 2 minutes. While it waits, the channel shows "retry 1/3" or "retry 2/3" with the next attempt time. Other errors fail right away.

Other messages you may see:

• "{channel} is paused." Resume the channel from its ⋯ menu, then retry.
• "This channel was removed." The channel was deleted after the post was scheduled.
• "{network} is not set up on this server." On a self-hosted server, the network's keys are missing. See the network's page under "For self-hosters".
• "This post is being published right now. Try again in a minute." Wait for publishing to finish before you edit.
• "This post has already been published. Duplicate it to post again." Use Duplicate to make a copy.

#Channel needs reconnecting

A channel shows "Reconnect needed" when the network rejects its sign-in, or when Postline can't refresh its access token. You may see "The connection to {channel} expired. Reconnect the channel." Owners and admins get a "Reconnect {channel}" notification, in the app and by email.

Posts to that channel can't go out until you reconnect it. You can't schedule new posts to it either: you see "{channel} needs to be reconnected."

1. In the sidebar, click the ⋯ menu next to the channel.
2. Choose Reconnect. Only owners and admins see this option.
3. For most networks that use sign-in, you go to the network and sign in again. For Mastodon and for networks that use a form (such as Bluesky, Lemmy or Telegram), the Add a channel dialog opens. Choose the network and enter the details again.
4. Retry any posts that failed with Retry failed.

#Media was rejected

Postline checks media against each network's rules before it schedules a post. Common messages:

• "{network} allows up to {n} files." Remove files. Each network page lists its maximum.
• "{network} does not take images or video." Twitch, Kick and Whop are text only.
• "{network} does not accept video here." For example Reddit, Google Business Profile, Lemmy, VK and the blog networks take images only.
• "{network} needs a video." YouTube needs exactly one video.
• "{network} posts need at least one image or video." Instagram, TikTok, Pinterest and Dribbble need media.
• Network-specific rules, for example "X allows one video per post, without other images." or "TikTok photo posts accept JPG or WebP images." See the network's page.

When you upload, images must be under the server's size limit ("Images must be under 10 MB" by default). Imported files must be JPG, PNG, GIF, WebP, MP4, MOV or WebM.

Some networks reject media when they publish:

• Bluesky images must be under 1 MB and videos under 100 MB.
• If a network can't process a video, the post fails with a message such as "X could not process the video" or "LinkedIn could not process the video."
• Facebook, Instagram and Threads download media from a public URL. If the server isn't public, the post fails with a message asking you to deploy Postline to a public address or use S3 storage. This only happens on self-hosted servers.

#Post is waiting for approval

If an owner or admin turned on Require approval for editors under Settings → Workspace, posts that editors schedule wait for approval. They go out only after an owner or admin approves them.

• Editors: your post shows as waiting for approval after you click Submit for approval. You get a notification when it's approved, or when it's sent back to draft (with a reason, if one was given).
• Owners and admins: open the post and click Approve or Send back. If the scheduled time has passed, you see "The scheduled time has passed. Pick a new time before approving." Change the time, then approve.

#Post went out late

• Retries. If the network had a temporary problem, Postline waited and tried again, about 1 minute and then 2 minutes later. See A post failed.
• Approval. A post waiting for approval doesn't go out until it's approved.
• Media processing. Videos are uploaded and processed by the network before the post is published. Large videos take longer.
• Self-hosters. The publishing worker checks for due posts every WORKER_INTERVAL_MS (5 seconds by default). If you set RUN_WORKER=false, you must run the worker as a separate process (node dist/worker.js or npm run worker). Otherwise posts don't go out. When the worker starts again, it publishes posts that are past due.

#I can't connect a channel

• "Choose a plan to connect channels." Your workspace has no plan. The workspace owner can choose one under Settings → Billing. Every plan starts with a free trial.
• "Your plan allows {n} channels. Upgrade or remove a channel first." You reached your plan's channel limit. Upgrade, or remove a channel you don't use.
• "Your plan allows {n} active channels. Upgrade or pause another channel first." This appears when you resume a paused channel.
• "Only workspace owners and admins can add channels." Ask an owner or admin to add it.
• "Verify your email address first." Open the link in the email you got when you signed up.
• The network shows "Setup needed". On a self-hosted server, the network's keys aren't set. See the network's page under "For self-hosters".
• "This connection link expired. Try connecting again." Start again from + Add.
• The network returned an error. Postline shows the network's message, for example "No Facebook Pages were shared. Reconnect and select at least one Page." Each network's page lists these messages under "Known issues".
• Self-hosters. The redirect URL registered with the network must be exactly {APP_URL}/api/channels/oauth/{network}/callback. Until the network approves your app, only the app's own test users can connect it.

#Emails aren't arriving

Postline emails people about failed posts, posts waiting for approval, channels that need reconnecting, invites, email verification and password resets.

If you don't get emails about failed posts, approvals or reconnects, check Settings → Account. Email me about important events must be on. You always see these events in the app.

For self-hosters:

1. Set RESEND_API_KEY to a Resend API key, and verify your sending domain in Resend.
2. Set MAIL_FROM to an address on that domain, for example Postline <no-reply@yourdomain.com>.
3. Or set SMTP_URL to use any SMTP server instead, for example smtps://user:password@smtp.example.com:465.

Without email set up, Postline doesn't send emails. It writes them to the server log instead, and invite links are shown in the app.