> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> PostQueen's hosted API is https://api.postqueen.ai. The public API base is https://api.postqueen.ai/public/v1 and takes the raw API key in the Authorization header, with no Bearer prefix.
> The MCP server for posting is https://api.postqueen.ai/mcp/YOUR_API_KEY (or /mcp with Authorization: Bearer YOUR_API_KEY). docs.postqueen.ai/mcp only searches these docs and cannot post.
> The API key is under Connections > API Keys in the app, and only workspace admins can see it.
# Troubleshooting agents
> What to do when an MCP connection or a postqueen CLI command fails, by symptom and by the exact message you see.
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 key address answers `400` with `Invalid API Key` when it does not know the key. Copy the key again from **Connections > API Keys** 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.
With the Bearer header on `https://api.postqueen.ai/mcp`, `Missing Authorization header` means the agent sent no header, and `Invalid API Key or OAuth token` means the key in it is wrong. The header must read `Authorization: Bearer YOUR_API_KEY`.
An admin may have rotated the key under **Connections > API Keys**, which stops the old key everywhere at once, or revoked a sign-in under **Connections > Approved Apps**. Put the new key in every agent that used the old one, or sign in again.
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.
Some agents start a sign-in when a server refuses them, so a wrong key can look like a sign-in request. Check the key first. If the agent supports it, you can use the [sign-in address](/mcp/introduction#sign-in-instead-of-a-key) instead.
* 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.
* Gemini CLI, Grok, Grok Bot, Perplexity Computer and NanoClaw cannot sign in. Give them the API key, in the key address or the Bearer header.
PostQueen has not completed this sign-in end to end yet. If it fails, use the key address.
It is connected to `docs.postqueen.ai/mcp`, which searches these docs only. Connect it to an address from [MCP server](/mcp/introduction) 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](/cloud/plans) |
| `: ... 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 |
| `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 | Use the post's own ID from `postsListTool` |
| `No AI image credits are available on this account.` | The plan's image credits for the month are used up | Wait for the next month, or move to a plan with more. See [plans](/cloud/plans) |
| `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](/cli/analytics#fix-a-missing-release-id) |
The **Upload Media** panel shows only in apps that can display MCP panels, such as Claude, Claude Cowork and ChatGPT. Elsewhere, give the agent a public link to the file so it can use `uploadFromUrlTool`.
No MCP tool can delete a post, change its text or time, or move it between draft and scheduled. Check the calendar, and do it there, or with the [CLI](/cli/managing-posts) or the [API](/public-api/introduction).
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:
```text wrap theme={"system"}
❌ 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.` | `POSTQUEEN_API_KEY` is not set where the command runs. `export POSTQUEEN_API_KEY=your_api_key` there. A scheduled job or an agent needs it 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 Keys** |
| `❌ 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. Run `postqueen auth:logout` and use the API key |
`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 `` 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 ` lists the required ones, drafts included |
| `"provider":"...","message":"Please fix your settings"` | A setting the network requires is wrong. Match `integrations:settings ` |
| `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](/cli/media-upload) |
| `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, refused runs included, 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](/cli/media-upload#if-an-upload-fails). A post whose analytics answer `{"missing": true}` is fixed on [analytics](/cli/analytics#fix-a-missing-release-id).
### Common mistakes
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`.
`-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`.
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.
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`.
`-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](/cli/media-upload#wait-for-a-video).
## 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](/agents/overview#three-ways-to-connect).
## Still stuck?
If you hit something that is not covered here, email
[support@postqueen.ai](mailto: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.