pitfalls

Buffer Pitfalls & Common Traps #

Skim this reference before composing commands and JSON payloads for Buffer CLI.

1. Scheduling Traps #

• mode: addToQueue is queued, not immediate: Use mode: shareNow to publish immediately. mode: shareNext jumps to the front of the queue. mode: customScheduled requires dueAt.
• schedulingType: notification does not auto-publish: It sends a push notification to the mobile app for a human to publish. Use schedulingType: automatic for hands-off publishing.
• addToQueue on a channel with no schedule: Silently lands in an empty queue slot. Inspect the channel schedule with buffer channels get --id <id> first.
• All times are ISO-8601 with offset: dueAt must include a timezone offset (e.g. 2026-05-06T17:00:00-05:00). Compute the offset from buffer config get timezone or buffer account --fields timezone. Never assume UTC.

2. Identifier Integrity #

• Never guess channel IDs: Always fetch with buffer channels list --output json. IDs look pseudo-random; invalid IDs will be accepted initially and fail on execution with vague errors.
• IDs are not portable across organizations: A channelId from Organization A cannot be used while authenticated against Organization B.

3. Input & Payload Formatting #

• --json overrides flags entirely: When both --json and individual flags are supplied, flags are dropped. Pick one style per command.
• Nested objects need --json: Per-service metadata.* and assets.* cannot be set via flat flags. Use the JSON path.
• Empty text without assets is rejected: Most channels require text or at least one image/video asset.
• Control characters are rejected: Strip ASCII control characters (U+0000–U+001F except whitespace) before sending.

4. Per-Service Minimum Payloads #

5. Twitter / X Threads #

When composing multi-post chains for Twitter/X via metadata.twitter.thread:

• The outer text MUST equal the first thread item's text:

{
  "text": "First tweet in thread",
  "metadata": {
    "twitter": {
      "thread": [
        { "text": "First tweet in thread" },
        { "text": "Second tweet in thread" }
      ]
    }
  }
}