# Troubleshooting

> What to do when a job is held, fails or ends unknown — every hold reason, every job error, and fixes for the most common problems.

Source: https://x.builera.app/docs/en/troubleshooting
Last checked: 2026-10-24

Start with the alert or the job's status: it always names the reason. Find it below.

## Common problems {#common-problems}

| What you see | Why | What to do |
|---|---|---|
| **VPS "…" is offline** | The VPS hasn't checked in for a while. | Make sure the VPS is running and online and the agent window is open. After a reboot, Windows must sign in for the agent to start. |
| **VPS needs an update** | The agent is older than X-Buddy requires. It still checks in and updates itself, but gets no jobs. | Nothing, usually: it installs the update as soon as no job is running and no Remote view is open. |
| **Proxy "…" can't connect** | The proxy doesn't answer, rejects its login, or is the wrong type. | Check expiry, address, port, username, password and type (HTTP or SOCKS5), then check it again on the **Proxy** page. |
| **Proxy "…" IP changed** | The proxy now exits from a different IP or place than before. The X accounts using it wait. | Fix the proxy so it exits where it did, then check it again. |
| **X account … was signed out of X** | X ended the session. | Sign in again through [Remote view](/docs/en/x-accounts#sign-in-through-remote-view). |
| **X account … needs X Chat unlocked** | X Chat is locked, or the saved passcode is wrong. | Save the right passcode in the X account's **Inbox** tab, or unlock it in Remote view. A wrong saved passcode is not retried, so X Chat doesn't lock. |
| **"…" is broken because X changed its interface** | X changed a page, so X-Buddy can't find the button it needs. | Wait: X-Buddy updates how it finds things on X without reinstalling the agent. This doesn't lower the X account's safety. |
| **Sync of X account … couldn't fetch …** | Part of a sync failed. Everything else is still usable. | It retries by itself. If it keeps happening, X probably changed how it shows that data. |
| **X account … is slowed down** | X reported a rate limit. | Work waits until 30 minutes after the latest rate-limit result, then resumes by itself unless another hold reason applies. See [Limits, run hours & safety](/docs/en/limits-and-safety). |
| **VPS display is too small for X** | The VPS screen is below 1024×720, often because the Remote Desktop window is small. | Enlarge or close Remote Desktop. Leave with **Exit Remote safely**. |

## Held jobs {#held-jobs}

A held job is waiting, not failed. X-Buddy checks one gate before handing out any job; when a reason clears, the job wakes up by itself and the gate checks again — so a second reason can show next.

### The X account {#the-x-account}

| Reason shown | It clears when |
|---|---|
| **X account paused** | You resume the X account. |
| **X account needs a safety review** | You resolve the issue on X and confirm the X account may run again. |
| **X account not signed in** | It signs in again (Remote view). |
| **X Chat is locked for this X account — …** | X Chat is unlocked. Only message sending waits; inbox sync continues. |
| **Remote viewing active** | You close Remote view. |
| **X account is busy with another job** | The current job finishes. One job per X account at a time. |
| **X rate limit reached — X account will resume automatically after a pause** | The 30-minute wait ends. |

### Limits and schedule {#limits-and-schedule}

| Reason shown | It clears when |
|---|---|
| **Outside run hours** | The next allowed window starts, or you change run hours. |
| **On a break** | The break ends. |
| **X account rest day** | The next working day. |
| **Not yet available during warmup** | Warm-up reaches the week that allows it, or you change warm-up. |
| **Daily limit reached** | Midnight in the X account's time zone, or you raise the limit. |
| **Rolling 7-day limit reached — waiting for capacity** | Older actions leave the 7-day window, or you raise the limit. |
| **Waiting for the required interval between actions** | The minimum gap has passed. |
| **Follow-unfollow protection: waiting for the required number of days** | Enough days have passed since the follow or unfollow. |
| **Recipient is on the do-not-contact list** | Only if you remove the person from the list — do that only if contacting them is right. |

### VPS, proxy and agent {#vps-proxy-and-agent}

| Reason shown | It clears when |
|---|---|
| **No VPS assigned** | You assign the X account to a VPS. |
| **VPS disconnected** | The agent checks in again. |
| **VPS needs an update** | The agent installs the required version. |
| **VPS has reached its Chrome instance limit** | Another Chrome window on that VPS closes. |
| **Proxy error or IP changed** | The proxy passes its check again. |
| **VPS display is too small for X (…)** | The screen is 1024×720 or larger. |
| **VPS agent reports a Core signature mismatch — …** | The agent installs a correct, signed version. |
| **VPS agent uses a protocol that is too old (or newer than the server) — …** | The agent and X-Buddy are on compatible versions. |

### Workspace and connections {#workspace-and-connections}

| Reason shown | It clears when |
|---|---|
| **System under maintenance** | Maintenance ends. |
| **Action disabled system-wide** | X-Buddy turns the action back on. |
| **Workspace suspended** | The workspace is active again. |
| **MCP / API connection is paused** | The connection is resumed. |
| **All workspace MCP / API connections are paused** | Connections are turned back on for the workspace. |
| **The connection creator no longer has permission to perform this action** | Someone with the right role creates the connection. |
| **Yielding to due automated jobs (after 5 consecutive instant commands)** | Due automated work has had its turn; the direct call runs about 30 seconds later. |

## Unknown outcomes {#unknown-outcomes}

Sometimes X-Buddy can't tell whether a write reached X — the page timed out, or the VPS stopped reporting. It never guesses and never simply does it again.

1. **It checks X first.** For follows, likes, reposts and similar actions, it reads X up to 3 times — right away, after 10 minutes and after 30 minutes — and records what it finds. These are reads only.
2. **Messages are different.** For a message, X-Buddy looks for it in the inbox. If it hasn't appeared after 40 minutes, the job says so and the message is **not resent automatically**.
3. **Then it asks you.** If it's still unclear, the job goes to **Needs review**. Check X, then choose:
   - **Done on X** — it happened; carry on.
   - **Retry** — it didn't happen; do it again.
   - **Stop** — don't do it.

### VPS quarantine {#vps-quarantine}

If a VPS finished work but couldn't report it in time, the result is kept on the VPS and shown on the **VPS & Agent** page, never resubmitted automatically. Check X and the activity log, then choose **Allow VPS deletion**. This deletes the VPS's stored copy of the result — it doesn't undo anything on X. The VPS sends its evidence to X-Buddy before deleting.

## Job errors {#job-errors}

| What the job says | What to do |
|---|---|
| The X interface has changed, so the required button could not be found. | Wait for X-Buddy's update; no reinstall needed. |
| The action was performed, but the result could not be verified on X. | Check X before retrying. |
| The message template has a field (e.g., @name) with no value for this contact — nothing was sent. | Fill in the field for this contact, or change the template. |
| The job's outcome on X is unknown — X-Buddy is automatically checking X again (up to 3 times in 30 minutes) before asking you. | Wait; see [Unknown outcomes](#unknown-outcomes). |
| This message hasn't appeared in the inbox after 40 minutes — … It won't be resent automatically. | Check the conversation on X before sending again. |
| Can't open this profile or post on X (it may have been deleted, locked, or renamed). | Check the target. |
| X doesn't allow this action for this person or post. | Nothing to fix in X-Buddy. |
| The VPS network connection is unstable. / X is taking too long to respond. | It retries; check the VPS network if it keeps happening. |
| Chrome on the VPS closed unexpectedly. | It retries; check free RAM on the VPS. |
| Today's limit for this action has been reached. | Wait for tomorrow or raise the limit. |
| Stopped because X says the X account needs attention (verification, locked, or limited). | Resolve it on X, then let the X account run again. |
| The proxy rejected the username or password. / Can't connect to the proxy. / Incorrect proxy type (HTTP or SOCKS5). | Fix the proxy. |
| X Chat is locked for this X account. / X says the saved X Chat passcode is incorrect. | Save the right passcode, or unlock in Remote view. |
| The agent version on your VPS doesn't support this action yet. | Wait for the agent to update. |
| The VPS didn't report results in time. | Check on X before trying again — it may already have happened. |
| The deadline has passed, so the job will no longer run. | Create it again with a later deadline if still needed. |
| This X account's browser profile is corrupted. | Contact the X-Buddy operations team; don't recreate the X account (its profile must stay the same). |
| The campaign's step sequence has an error. / This step's message template is empty. | Fix the campaign. |

Any other error shows **The job didn't complete.** — see the **Activity log** for details.

## Still stuck? {#still-stuck}

- [Core concepts](/docs/en/concepts#job-outcomes) explains each job status.
- For API errors, see [Errors](/docs/en/errors).