Troubleshooting agents

Find the symptom or the message you see. Most failures come from the key, from a setting the network requires, or from media that was not uploaded to PostQueen first.

The agent will not connect over MCP

The connection fails with Invalid API Key

The key address answers 400 with Invalid API Key or no active subscription. Either the key is wrong, or the workspace has no trial or plan: start or renew it in Billing. For the key, copy it again from Connections > API key and paste the whole address, https://api.postqueen.ai/mcp/YOUR_API_KEY, with no space or quote around the key. Only a workspace Admin or Super Admin can reveal the key; other members see it masked.

The connection fails with 401

With the Bearer header on https://api.postqueen.ai/mcp, Missing Authorization header means the agent sent no header. Invalid API Key or OAuth token, or no active subscription means the key or token in it is wrong, or the workspace has no trial or plan (see Billing). The header must read Authorization: Bearer YOUR_API_KEY.

It worked before, and stopped

An admin may have rotated the key under Connections > API key, which stops the old key everywhere at once. Or the person who approved a sign-in revoked it under Connections > Approved Apps, or the workspace’s trial or plan ended. Put the new key in every agent that used the old one, or sign in again.

Connected, but no PostQueen tools

Many agents load their tools when a session starts. Start a new session, or reload the servers: /mcp in Claude Code, /reload-mcp in Hermes Agent, a restart in most editors. Then ask the agent to list your PostQueen channels.

Only a workspace Admin or Super Admin can approve the sign-in. Ask one to connect the agent.
Paste https://api.postqueen.ai/mcp-oauth-dynamic with no slash at the end, and leave any client ID and secret fields empty. In Claude’s two-step dialog, choose Register automatically under OAuth client.
The Grok Bot, Grok and NanoClaw guides use the API key. Give it to them the way their guides show; NanoClaw keeps it in its OneCLI vault.

If it still fails, use the key address.

The agent answers from the docs but cannot post

It is connected to docs.postqueen.ai/mcp, which searches these docs only. Connect it to an address from MCP server instead.

An MCP tool returns an error

What the agent reports	What it means	What to do
`This channel needs to be reconnected before you can schedule posts. Please reconnect it from Channels.`	The channel’s sign-in to its network expired, or it is turned off	Reconnect or turn on the channel on the Channels page, then ask again
A channel is missing from the list	`integrationList` leaves out channels that are turned off, need to be reconnected or were not finished connecting	Fix the channel on the Channels page
`This workspace has no active plan, or no posts left on its plan this month. ...`	The workspace has no active trial or plan	Start or renew the plan in Billing. See plans
`<channel>: ... please fix it, and try integrationSchedulePostTool again.`	The post is missing a setting, or is too long for the network	The agent should read `integrationSchema` for that network and try again
`Your post should have at least one character or one image.`	An item in the post is empty	Give every item text or media
`File must have a valid extension: .png, .jpg, .jpeg, .gif, .webp, or .mp4`	An attachment is not a supported file	Bring the file in with `uploadFromUrlTool`, the upload panel or `generateImageTool`, and use the `path` it returns
`The thumbnail must be a .jpg, .jpeg or .png file`	An attachment’s `thumbnail` is not a JPEG or PNG	Upload a `.jpg`, `.jpeg` or `.png` picture and use its `path` as the `thumbnail`
`Method "..." not found for this integration, ...`	The agent asked for a helper this network does not have	The agent should use a `methodName` from `integrationSchema`
`The channel was disconnected because its token expired, ...`	The network no longer accepts the channel’s sign-in	Reconnect the channel on the Channels page
`Only scheduled posts that were not published yet (or drafts) can be updated`	`postSettingsTool` was used on a published or failed post	Settings can only change before a post goes out
`The publish time of this post already passed, it cannot be updated`	The post is due or going out now	Nothing to change: check it on the calendar
`This id belongs to a comment, pass the id of the main post`	The agent used a comment’s ID with `postSettingsTool` or `deletePostTool`	Use the post’s own ID from `postsListTool`
`Post not found` from `deletePostTool`	The ID is not a post of this workspace, or the post was already deleted	List the posts again with `postsListTool` and use the post’s `id`
`Not enough credits: this costs N and the balance is N.`	The workspace’s credits do not cover the image, video or X post	Add credits on Billing, or ask for something that costs less, such as a lower `quality` image
`missing_release` from `analyticsPostTool`	PostQueen does not know the post’s ID on the network	Connect the post to its published copy, then ask again. See analytics

No upload panel appears

The Upload Media panel shows only in apps that can display MCP panels, such as Claude, Claude Cowork and ChatGPT. Elsewhere, upload the file on PostQueen’s Media page, in the workspace the agent is connected to, and tell the agent its name: it finds the file with mediaListTool. An agent that runs commands on your computer can upload it itself with uploadLinkTool, or with postqueen upload, and a file on a public link goes in with uploadFromUrlTool.

The agent says it moved a post or changed its text

No MCP tool can change a post’s text or time, or move it between draft and scheduled. Check the calendar, and do it there, or with the CLI or the API.

A deleted post is still on the network

deletePostTool deletes a post from PostQueen only. A post that was already published stays live on the network: delete it there too.

A video post failed

A video is prepared after it is uploaded, and its file can change when that is done. From the upload panel, wait until uploadWidgetStatusTool says ready before the post goes out. For a video from a link, check the post on your calendar before its time.

A CLI command fails

When the API refuses a command, the CLI prints one line to stderr and exits with code 1. The line says which command gave up, then what the API answered:

❌ Failed to create post: Request failed: API Error (400): {"statusCode":400,"provider":"bluesky","name":"PostQueen Bakery","message":"post is too long, please fix it"}

In the message	What it points to
`API Error (401)`	The key, or the workspace’s plan
`API Error (404)`	A wrong ID
`API Error (400)`	A post or a setting the API refused
`API Error (429)`	The hourly limit: 30 `posts:create` runs or 300 uploads per workspace
`Request failed` with no `API Error`	The API was not reached: check your connection

The key

Message	What to do
`❌ Error: No authentication found.`	The CLI is not signed in, and `POSTQUEEN_API_KEY` is not set where the command runs. Run `postqueen auth:login`, or set the key there. A scheduled job or an agent on another machine needs the key in its own environment
`❌ Not authenticated.`	The same, reported by `auth:status`
`API Error (401): {"msg":"Invalid API key"}`	The key is wrong or was rotated. Copy it again from Connections > API key
`❌ Credentials are expired or invalid. Please re-authenticate.`	`auth:status` checked the key and the API refused it. Same fix
`API Error (401): {"msg":"No subscription found"}`	The workspace has no active trial or plan. Start or renew it in Billing
`API Error (401): {"msg":"Invalid OAuth token"}`	A saved `auth:login` token, or a `pos_` token in `POSTQUEEN_API_KEY`, no longer works: it was revoked, or the person who approved it left the workspace. Run `postqueen auth:login` again

auth:status names the method it uses. If it says OAuth2 although you set a key, a saved login in ~/.postqueen/credentials.json is overriding the key: postqueen auth:logout removes it.

Flags

These are caught before anything is sent. Each prints a line starting with ❌ on stderr, and the command exits 1. A usage error ends with the help to read, such as Run "postqueen posts:create --help" for usage.

Message	What to do
`Either --content or --json is required`	Pass `-c "text"`, or `--json file.json`
`--integrations is required when not using --json`	Add `-i` with channel IDs from `integrations:list`
`--date is required when not using --json`	Add `-s "2026-10-01T09:00:00Z"`. There is no default date
`❌ Failed to parse settings JSON: ...`	The `--settings` JSON is broken, usually by shell quoting. Wrap it in single quotes
`❌ JSON file not found: ...`	Check the path you gave `--json`
`Invalid values: Argument: status, ...`	`posts:status` takes `draft` or `schedule` only
`Not enough non-option arguments: got 0, need at least 1`	A required ID or file is missing, such as the `<id>` of `posts:delete`
`Missing required argument: status`	`posts:status` needs `--status draft` or `--status schedule`
`Unknown command: ...`	The command name is misspelled. `postqueen --help` lists the commands
`Unknown argument: ...`	A flag name is misspelled. Flag names are case-sensitive: `--startDate` and `--start-date` work, `--startdate` does not
`--... was given more than once, but takes one value`	Give the flag once. Only `-c` and `-m` repeat, once per item
`❌ Empty integration ID in --integrations "..."`	`-i` has an empty entry, usually from a stray or trailing comma such as `-i "id1,"`

Posts

Message	What to do
`Integration with id ... not found`	The channel ID is wrong or the channel was removed. Run `integrations:list`
`posts.0.settings.who_can_reply_post must be one of the following values: ...`	A required setting is missing, here X’s. The path names the channel entry and the field. `integrations:settings <id>` lists the required ones, drafts included
`"provider":"...","message":"Please fix your settings"`	A setting the network requires is wrong. Match `integrations:settings <id>`
`post is too long, please fix it`	The text is over the channel’s `maxLength`
`Your post should have at least one character or one image.`	An item has no text and no media
`File must have a valid extension: .png, .jpg, .jpeg, .gif, .webp, or .mp4`	Pass a `path` from `postqueen upload`, of a type posts accept. See upload media
`type must be one of: draft, schedule, now, update`	The `type` in your `--json` file is wrong. Use `schedule`, `draft` or `now`
`Cannot change status of a published or errored post`	`posts:status` works only before a post goes out
`API Error (404): {"msg":"Tool not found"}`	`integrations:trigger` got a helper name the channel does not have. The names are under `tools` in `integrations:settings`
`API Error (429)`	The workspace reached its 30 `posts:create` runs in an hour or its 300 uploads. Wait an hour from the run that went over, and put several channels in one `-i` rather than one command per channel

Upload errors are on upload media. A post whose analytics answer {"missing": true} is fixed on analytics.

Common mistakes

jq fails on the first line

Most commands print a status line before the JSON. Drop it: postqueen integrations:list | tail -n +2 | jq '.'. posts:missing prints JSON only, so it needs no tail.

The same letter means two things

-s is the date on posts:create and the status on posts:status. -d is minutes between items on posts:create, days on the analytics commands, and JSON input on integrations:trigger.

It works in my terminal, not in the job or the agent

The job or the agent runs in its own environment and does not read your shell profile. Set POSTQUEEN_API_KEY there, and send stderr to the log (2>&1) so the error is not lost.

A script checks the key with auth:status

From 2.0.24, auth:status exits 1 when no key is set, when the API refuses it, and when it could not be checked, so postqueen auth:status > /dev/null || exit 1 works. Older versions exit 0 in every case: update with npm install -g postqueen@latest.

A file path or a link in -m

-m takes only a path returned by postqueen upload. Upload the file first. A MOV has to finish converting to MP4 before it can go into a post: see upload media.

Something the route cannot do

Some things are not a failure: the route you use does not offer them yet. What MCP, the CLI and the API can each do is on AI agents.

Still stuck?

If you hit something that is not covered here, email support@postqueen.ai with what you saw and when. Send the exact command or prompt, the agent you use and the full message. Never send your API key.

Start here

Assistants and bots

Coding agents

Editors and more

MCP reference

CLI reference