> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autogrowth.farm/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AutoGrowth runs social accounts on real phones. Everything a page describes happens on a physical device in the customer's own fleet, never through a social platform's API.
> The Companion is a macOS desktop app that runs on the customer's own Mac and manages the phones over USB — iPhones through WebDriverAgent, GrapheneOS phones through ADB and scrcpy. Nothing runs while the Companion is closed.
> The Companion builds, signs and installs WebDriverAgent on each iPhone itself. Never tell a customer to sign WebDriverAgent by hand in Xcode; Xcode is a prerequisite the Companion drives, not a step the customer performs.
> Autogrowth MAX is a one-time, invite-only lifetime license bought from the organization's credit balance, not a subscription tier. It is required to run any automation, workflow or Incubator program. Without a price set for that organization, the purchase is refused.
> An automation is one of AutoGrowth's built-in definitions; a script is a graph the customer builds in the Script Builder. The Script Builder is locked platform-wide, so never present building a script as something a customer can do today.
> An API key is a bare 64-character hex string with no prefix. It is shown once, at creation, is sent as `Authorization: Bearer <key>`, and can never be read back.
> An API key sees only the key owner's own accounts, content, collections, prompts, scripts and executions. Devices and tags are organization-scoped, and a non-owner sees only the devices assigned to them or carrying one of their tags. The automation catalog is global.
> There is no pagination. List endpoints return the whole set; the only limiting parameter anywhere is `limit` on `GET /v1/executions`, which defaults to 50 and has no offset to page with.
> Remote control and the live screen are dashboard-only, over WebSocket and MJPEG. Neither is part of the public API.
> The MCP server is hosted at https://mcp.autogrowth.farm and authenticates with OAuth. It is not an npm package and there is nothing to install locally. Its tools inherit exactly the scope of the API key behind them.
> Android support is partial and GrapheneOS-only: those phones appear in the fleet and can be watched and remote-controlled, but they cannot run scripts or automations.
> Never document Hi Katie or any persona feature. When a page and the code disagree, the code wins — check a claim against the source before repeating it.

# Troubleshooting

> Sorted by what you are looking at: a phone that will not appear, a build that fails, a run that never happened, an upload that will not upload.

Find the symptom, not the cause. Every message quoted here is one the product
actually shows.

If nothing below matches, skip to [Getting help](/guides/getting-help) — and send
the exact text you are looking at.

## The Companion will not open, or keeps signing me out

<AccordionGroup>
  <Accordion title="A “Security Error” box appears and the app closes">
    The Companion checks its surroundings before it opens a window. A debugger, a
    proxy, a traffic-capture tool or a modified copy of the app all stop it.

    Close any network-analysis or debugging software and open the app again. If
    you did not install the app from a link an owner gave you, install it again
    from a fresh one.
  </Accordion>

  <Accordion title="“This license key isn't valid. It may have been mistyped, deleted, or revoked.”">
    Usually a stray space, a partial paste, or a key that was deleted in the
    dashboard.

    Go to **Settings → Companion Keys**, create a new key, and paste that. A real
    key is 64 letters and digits with no dashes, whatever the placeholder in the
    field suggests.
  </Accordion>

  <Accordion title="“This license key is already bound to another computer. Contact support to move it.”">
    A key locks to the first Mac that signs in with it, permanently, and there is
    no way to unbind it.

    Delete that key in **Settings → Companion Keys**, create a new one, and sign
    in with it on this Mac. Your phones are not affected.
  </Accordion>

  <Accordion title="“Your session ended. Enter your license key to continue.”">
    The Companion re-checks the key every five minutes. If the Mac loses internet
    for long enough, the check fails and you are signed out.

    Get the Mac back online and paste the key again. If it happens repeatedly,
    look at a VPN, a firewall or a corporate proxy on that network.
  </Accordion>

  <Accordion title="“Update Required” and the app quits">
    The version you have is too old to be used. This is not optional and there is
    no automatic updater.

    Ask an owner for a new download link in **Settings → Downloads**, install the
    new DMG over the old app, and sign in again with the same key.
  </Accordion>

  <Accordion title="“Missing System Dependencies”">
    Neither iPhones nor GrapheneOS phones can be managed until at least one
    platform's tools are installed. The screen lists each missing tool with the
    command that installs it and a **Copy** button.

    Run them in Terminal, then press **Re-check Dependencies**. The full list is
    on [Install the Companion](/guides/install-the-companion#install-the-tools-it-needs).
  </Accordion>

  <Accordion title="“Download link has already been used” or “has expired”">
    Installer links work once and expire — 24 hours by default. Ask an
    organization owner for a new one.
  </Accordion>
</AccordionGroup>

## My phone does not appear in the Companion

<AccordionGroup>
  <Accordion title="Nothing shows up at all">
    Work through these in order. They are the Companion's own five steps and they
    fix this almost every time.

    1. Unplug the iPhone, wait about ten seconds, and plug it back in.
    2. Use a known-good Apple cable, in a port on the Mac itself — no hubs.
    3. Unlock the iPhone and tap **Trust** if it asks.
    4. On iOS 17 and newer, make sure you approved the macOS password prompt.
    5. Press **Build** again.

    The Companion scans every few seconds, so give it a moment rather than
    restarting the app.
  </Accordion>

  <Accordion title="“Device not visible to Xcode. Please unplug and replug your iPhone, or try a different USB cable/port.”">
    The Mac cannot see the phone over USB. Same five steps as above. If one cable
    works and another does not, it was the cable.
  </Accordion>

  <Accordion title="A phone plugged in on iOS 17 or newer looks absent">
    This is usually the macOS password prompt being dismissed. Without it there is
    no tunnel to the phone and it looks unplugged.

    Press **Build** or **Start** again and type your Mac password when macOS asks.
    The message that goes with it is "Admin permission is required to start the
    iOS 17+ device tunnel. Please approve the password prompt and try again."
  </Accordion>

  <Accordion title="An Android phone shows “Unsupported (stock Android)”">
    Only GrapheneOS phones can be managed. A stock Android phone is listed so you
    can see it was noticed, and nothing more will happen with it. See
    [Android phones](/guides/android-phones).
  </Accordion>

  <Accordion title="“USB debugging not authorized — accept the RSA prompt on the phone”">
    The GrapheneOS phone has not authorised this Mac. Look at the phone, tick
    **Always allow from this computer**, and accept.
  </Accordion>
</AccordionGroup>

## My phone shows…

<AccordionGroup>
  <Accordion title="“Tap Trust on iPhone”">
    The phone has not trusted this Mac. Unlock it, tap **Trust** on the "Trust
    This Computer?" popup, and enter the passcode.

    There is nothing to press in the Companion afterwards — it keeps asking and
    lights the row up by itself.
  </Accordion>

  <Accordion title="“Reading device info…”">
    The Companion is still identifying the phone and is retrying on its own.

    If it never clears, reseat the cable. The tooltip says the same: "Could not
    read this device's info yet — retrying automatically. Reconnect the cable if
    this persists."
  </Accordion>

  <Accordion title="“Needs Setup” or “Detected”">
    The phone is seen but has no agent installed. Press **Build**.
  </Accordion>

  <Accordion title="“Offline” in the dashboard while it is plugged in">
    The dashboard calls a phone offline when it has not heard from the Companion
    for about 90 seconds. Check that the Companion is open and signed in on the
    Mac, and that the Mac is awake and online.

    A sleeping Mac takes the whole fleet offline.
  </Accordion>

  <Accordion title="A badge reading “No Slots”, “Slot Expired” or “Slot Removed”">
    The phone is connected fine — it just has no paid slot behind it. Being
    plugged in and having a slot are separate things, and a phone can be Ready and
    still refuse to stream or run anything.

    Press the button on the row, or fix it in the dashboard under **Settings →
    Billing**. See [Billing](/guides/billing).
  </Accordion>

  <Accordion title="“This device is already registered to another account…”">
    The phone is registered to a different organization. It has to be removed
    there before it can join yours. If you do not know where, contact support with
    the phone's UDID.
  </Accordion>
</AccordionGroup>

## Build or Start fails

<AccordionGroup>
  <Accordion title="“Developer Mode is disabled…”">
    On the iPhone: **Settings → Privacy & Security → Developer Mode**, switch it
    on. The phone restarts and asks you to confirm with **Turn On**. Then press
    **Build**.
  </Accordion>

  <Accordion title="“WDA did not become ready within 90s…”">
    Almost always the developer app not being trusted on the phone. This is a
    second, separate Trust step from the one at the cable.

    On the iPhone: **Settings → General → VPN & Device Management**, tap the
    developer app, choose **Trust**. Then press **Start** again.
  </Accordion>

  <Accordion title="“iPhone is locked. Please unlock your iPhone and try again.”">
    Unlock the phone, keep it awake, and press **Start**. Nothing needs
    rebuilding. Fleet phones are normally left with auto-lock off.
  </Accordion>

  <Accordion title="“all Apple accounts at capacity, add another”">
    Apple allows 100 devices per developer account per year, and every account you
    have connected is full. Connect another Apple Developer account in **Settings
    → WDA Signing**. See [WebDriverAgent](/guides/wda-signing#server-signing).
  </Accordion>

  <Accordion title="“No Apple accounts connected” or “Apple account not bootstrapped”">
    Server signing is selected but the setup is not finished. In **Settings → WDA
    Signing**, press **Add account**, fill in the App Store Connect details, then
    press **Bootstrap** on the row.
  </Accordion>

  <Accordion title="“Apple is still verifying this device — this typically resolves overnight.”">
    Apple has not finished registering the phone on your developer account.
    Nothing is broken. Press **Build** again in a few hours.
  </Accordion>

  <Accordion title="“2FA timed out (no code entered)”">
    The Apple two-factor prompt gives you five minutes. Press **Build** again and
    have the code ready.
  </Accordion>

  <Accordion title="“No available WDA ports” or “No available MJPEG ports”">
    Too many phones are started on one Mac. Stop the ones you are not using, or
    move part of the fleet to a second Mac.
  </Accordion>

  <Accordion title="“Failed to download signed WDA (HTTP …)”">
    A network hiccup or a bad build on our side. Press **Build** again. If it
    repeats on the same phone, send the message to support.
  </Accordion>

  <Accordion title="A phone restarts its agent on its own">
    Expected. The Companion checks each running phone every 30 seconds, restarts
    the agent after two failed checks, and rebuilds after three failed restarts.
    You will see it go **Starting** without touching it.
  </Accordion>
</AccordionGroup>

## Remote control will not open, or the screen is blank

<AccordionGroup>
  <Accordion title="The Remote Control button does nothing">
    Hover it. The tooltip says **Remote Control unavailable** and gives the reason
    — the phone is offline, the stream is not active, the agent is still being
    installed, or the phone is in an error state.

    In most cases the answer is to press **Start** on that phone in the Companion.
  </Accordion>

  <Accordion title="“Phone is not streaming — check the Companion app”">
    The agent is not running on that phone. Open the Companion and press
    **Start**.
  </Accordion>

  <Accordion title="“Video froze — reconnecting…” or “Stream ended — reconnecting…”">
    The picture stalled. The viewer reconnects on its own, so wait a few seconds
    first.

    If it does not come back: wake the phone, then **Stop** and **Start** it in
    the Companion. A flaky network on either end causes this too.
  </Accordion>

  <Accordion title="“Device slot has expired. Renew your slot to access streaming.”">
    The phone's paid slot lapsed. Renew it under **Settings → Billing**. Slots do
    not renew themselves and there is no grace period.
  </Accordion>

  <Accordion title="“This phone is not part of your organization”">
    You are signed in to a different organization from the one the phone belongs
    to. A user belongs to exactly one organization, so this means the phone is
    somewhere else — it has to be released there.
  </Accordion>

  <Accordion title="“Streaming server unavailable — retrying…” or “No streaming servers are online”">
    Either a relay outage on our side or a network that blocks the connection. Try
    another network first. If it persists everywhere, it is ours — write to
    support.
  </Accordion>

  <Accordion title="“Device not connected” when tapping">
    The Companion holding that phone dropped off between the video loading and
    your tap. Check the Companion is open, then reload the page.
  </Accordion>

  <Accordion title="A GrapheneOS profile shows “Locked — auto-unlock failed”">
    The saved PIN did not work, and the Companion stopped after one attempt on
    purpose — repeated failures lock the phone out entirely, and a locked-out
    GrapheneOS phone cannot be recovered remotely.

    Unlock the phone by hand and correct the PIN in the device's **Containers**
    tab. Profiles protected by a pattern or a password can never be unlocked
    remotely.
  </Accordion>
</AccordionGroup>

## A run failed with…

<AccordionGroup>
  <Accordion title="“Autogrowth MAX is required to run automations.”">
    Automations, workflows and the Incubator all need Autogrowth MAX, a one-time
    lifetime license. It is offered by invitation, so if your organization has no
    price set the upgrade dialog reads **Invite only**. See
    [Billing](/guides/billing).
  </Accordion>

  <Accordion title="“The Create Account add-on is required to run this automation.”">
    Creating Instagram accounts is a separate one-time purchase for the whole
    organization. Buy it under **Settings → Billing**.
  </Accordion>

  <Accordion title="“Device slot has expired. Renew your slot to schedule executions.”">
    The phone's slot lapsed. Renew it, then queue the run again. A phone with no
    live slot is skipped silently by the scheduler, so its runs never start.
  </Accordion>

  <Accordion title="“Selected account is not linked to this device”">
    The account you picked is not linked to the phone you picked. Open the
    account, use **Link iPhones**, and try again. See
    [Accounts](/guides/accounts).
  </Accordion>

  <Accordion title="“No visible element found matching: …”">
    The phone was not on the screen the automation expected. The usual causes are
    an app update that moved things, a popup in the way, the app being left on a
    different screen, or the phone being in another language.

    Put the app back on its home screen and run it again. Turning on **AI
    recovery** when you schedule helps with unexpected popups. If one automation
    fails this way repeatedly, send us the run's log.
  </Accordion>

  <Accordion title="“Claude API key not configured. Please set it in Settings.”">
    **AI recovery** was switched on for the run but your organization has no
    Claude API key. Add one under **Settings → Integrations**, or turn the toggle
    off.
  </Accordion>

  <Accordion title="“Execution interrupted — never finalized”">
    The Mac crashed, slept, quit the Companion or lost its connection while the
    run was in progress.

    Keep the Mac awake and online — turning off sleep on the Mac is worth doing
    once. Then re-run.
  </Accordion>

  <Accordion title="“{App} is not installed in this container — install it on the phone first”">
    The app is missing inside the container the run targeted. Install it in that
    container on the phone. See [Containers](/guides/containers).
  </Accordion>

  <Accordion title="“SMS code not received within … seconds”">
    The SMS provider never delivered a verification code. Check that the provider
    account has credit and that the country you picked has numbers available, then
    run it again.
  </Accordion>
</AccordionGroup>

## A run never happened

<AccordionGroup>
  <Accordion title="It is still “Pending” long after its time">
    Pending means it is queued and waiting for the phone. It is not lost: it is
    retried every time the Companion checks in.

    Bring the phone and its Mac back online. Runs already queued behind another
    run on the same phone also wait — one phone runs one job at a time.
  </Accordion>

  <Accordion title="It went “Skipped”">
    The phone never became available in time: "Execution expired — device never
    became available within 2h of the scheduled time".

    Schedule it again with the phone online, or leave the fleet running so it is
    online when the time comes.
  </Accordion>

  <Accordion title="A workflow ran, but one step did not">
    A posting step whose collection has nothing usable left in it is skipped, and
    the rest of the routine still runs. The workflow records a warning saying so —
    either the step has no collection at all, or the collection has run short.

    Collections drain: media that has been posted comes out of the pool, because
    reposting risks a ban. Add more media. See
    [Collections](/guides/collections).
  </Accordion>

  <Accordion title="Nothing at all is running on any phone">
    Check, in this order: the Companion is open and signed in, the Mac is awake,
    the phones show **Running**, and the slots are live. Any one of those being
    false stops everything downstream.
  </Accordion>
</AccordionGroup>

## Uploads and content

<AccordionGroup>
  <Accordion title="“Upload failed” with no reason">
    This message is generic and is very often the storage quota rather than
    anything wrong with the file.

    Check **Settings → Billing** and look at the **Storage** tile before assuming
    it is the file. You get 20 GB per active phone slot.
  </Accordion>

  <Accordion title="“Storage limit exceeded. Using …GB of …GB.”">
    The library is full. Delete media you no longer need, or add a phone slot —
    storage comes with slots and cannot be bought on its own.
  </Accordion>

  <Accordion title="“Unsupported file type” or “Over 100MB”">
    The library takes images and videos, up to 100 MB per file. Compress or
    convert the file.
  </Accordion>

  <Accordion title="“Failed to get Drive access token. Make sure Google Drive is connected.”">
    Reconnect Google Drive under **Settings → Integrations**. Imports are capped at
    20 files at a time and land with no collection assigned, so move them into one
    afterwards.
  </Accordion>

  <Accordion title="“WDA is not running. Please start WDA first.”">
    Pushing media to a phone needs a live agent. Press **Start** on that phone.
  </Accordion>
</AccordionGroup>

## Accounts

<AccordionGroup>
  <Accordion title="An account is stuck on “Warming” and never shows stats">
    **Only Instagram and TikTok accounts are ever scraped.** An X or Threads
    account will stay on Warming forever and never show follower numbers. That is
    how it works today, not a fault.

    An Instagram or TikTok account that has just been added is picked up within
    about half a minute, and everything else is refreshed once a day.
  </Accordion>

  <Accordion title="An account shows a red “Error” pill">
    The last attempt to read its public profile failed — a rate limit, a wrong
    handle, or a platform hiccup. The next daily pass usually clears it.

    The underlying reason is not shown in the dashboard, so if it stays red for
    days, send us the handle.
  </Accordion>

  <Accordion title="“Already tracking this account”">
    The handle is already in your list. If you meant to add another phone to it,
    re-adding the same handle with a different phone links that phone instead of
    erroring.
  </Accordion>

  <Accordion title="“Assign a phone to this account first”">
    The action needs the account to be linked to a phone. Open the account and use
    **Link iPhones**.
  </Accordion>

  <Accordion title="Engagement reads 0.0%">
    Engagement is not calculated today. Read followers and the 14-day trend
    instead.
  </Accordion>
</AccordionGroup>

## Refusals and money

<AccordionGroup>
  <Accordion title="“Insufficient permissions”">
    The most common rejection in the product. Your role does not include the
    permission the action needs. Ask an organization owner to grant it — owners
    bypass every permission check, so they will not see the error themselves.
  </Accordion>

  <Accordion title="“Insufficient credits. Need $…”">
    Everything is paid from your organization's credit balance. Top it up under
    **Settings → Billing**; credits arrive when the payment confirms, not on
    redirect.
  </Accordion>

  <Accordion title="“No available phone slots. Purchase a slot in the billing settings to add devices.”">
    Every slot you own is already taken by a phone. Buy another slot, or remove a
    phone you no longer use.
  </Accordion>

  <Accordion title="“Autogrowth MAX is invite-only. Contact us for access.”">
    MAX has not been offered to your organization, so there is no price to charge.
    Write to us.
  </Accordion>

  <Accordion title="“Container payment failed” or “Container billing suspended”">
    The monthly container charge could not be taken from your credit balance. It
    is retried daily for seven days. After that, new containers are blocked while
    the ones you already have keep running. Add credits.
  </Accordion>
</AccordionGroup>

## Still stuck

The Companion's **Sprout** panel keeps an **Activity** feed of everything that has
gone wrong on that Mac, with a suggested fix where it has one. When it does not,
it shows the raw message under "Something went wrong" — that raw text is exactly
what support needs.

<CardGroup cols={2}>
  <Card title="Getting help" icon="life-ring" href="/guides/getting-help">
    Where to write, and what to send with it.
  </Card>

  <Card title="What AutoGrowth does not do" icon="ban" href="/guides/what-autogrowth-does-not-do">
    Check whether the thing you are chasing is a limit rather than a bug.
  </Card>
</CardGroup>