Troubleshooting

Common problems with BitPull and how to solve them, from the exact message you see to the fix. Kept up to date with every version.

To check a specific computer run bitpull doctor · help.json · llms.txt

Lending is on in the app, but the network does not show this computer

Cause: The master switch "Lending on" is off (Pause / Resume only pauses lending that is already on), or a rule blocks lending right now: computer in use (idle minutes), on battery, outside the chosen hours, a daily/weekly/monthly limit reached, or almost no memory offered.

  1. In "Lending rules" tick "Lending on" and press "Save rules".
  2. Set "Only after minutes of inactivity" to 0 to lend while you use the computer.
  3. Offer enough memory: "Max memory (MB)" is in megabytes, e.g. 4096 = 4 GB.
  4. Read the line under the lending status: it says what the network sees or why nobody can use the computer.
  5. From a terminal or an AI assistant: bitpull status, then bitpull set enabled=on idleMinutes=0 maxMemoryMb=4096

Messages: Lending is switched off, Lending resumed, 0 lending now

Fixed in BitPull 0.1.10 shows the reason in the app

"Nobody can use this computer yet: no job can run here"

Cause: Lending is on, but this computer has neither a working sandbox (Docker or Apple Container passing BitPull's isolation check) nor an AI model to offer. The message continues with the exact reason.

  1. Follow the reason shown after the message (the entries below cover the common ones).
  2. Or download an AI model in "AI models to share" (models need Ollama or the built-in engine, not Docker).
  3. Then press "Check again" in "Set up this computer"; BitPull also retries by itself every 5 minutes.

Messages: Nobody can use this computer yet, docker: rejected

Fixed in BitPull 0.1.13 retries a failed check every 5 minutes

"Docker cannot download images because its Docker Hub login is no longer valid"

Cause: The Docker Hub account saved in Docker Desktop has expired credentials, so every image download fails, even of public images.

  1. Open Docker Desktop, click your account (top right) and choose Sign out.
  2. Sign in again, or stay signed out (public images download without an account).
  3. On Linux run: docker logout
  4. In BitPull press "Check again".

Messages: failed to authorize: failed to fetch oauth token, 401 Unauthorized, Docker Hub login is no longer valid

Docker Desktop is installed but BitPull says it is not installed (Windows)

Cause: BitPull looked for Docker only in the default folder and in the PATH it had when it started; Docker installed later, elsewhere or per user was not found.

  1. Update BitPull (Check for updates); version 0.1.8 or later finds Docker in every install location and re-reads the PATH.
  2. Start Docker Desktop and wait until it is running, then press "Check again".
  3. If BitPull shows a reason after "Docker" in "Set up this computer", follow it; the Windows user must be in the docker-users group.
  4. In PowerShell: bitpull doctor shows what is detected and why.

Messages: docker not found in PATH, not installed

Fixed in BitPull 0.1.8

"Docker Desktop is unable to start"

Cause: Docker Desktop itself does not start, usually because WSL 2 needs an update, virtualization is off, or it needs a restart.

  1. Restart the computer and wait 2-3 minutes for Docker Desktop (the whale icon stops moving).
  2. Update WSL: open PowerShell as administrator and run: wsl --update ; then restart.
  3. Open Docker Desktop and read its own error: e.g. "Virtualization support not detected" means enabling virtualization in the BIOS/UEFI.
  4. Then press "Check again" in BitPull.

Messages: Docker Desktop is unable to start, cannot download image busybox

Docker Desktop: "Shared folder invalid: one or more shared directories are missing"

Cause: BitPull versions before 0.1.12 shared a temporary folder with Docker for each job; if file sharing was allowed, Docker kept those folders in its settings after BitPull deleted them.

  1. Choose "Remove from configuration" (not "Create missing directories").
  2. Update BitPull to 0.1.12 or later: jobs no longer share any folder with Docker, so this cannot happen again.

Messages: shared folder invalid, one or more shared directories, Create missing directories, Remove from configuration

Fixed in BitPull 0.1.12

Docker Desktop asks for file sharing permission at every job

Cause: BitPull versions before 0.1.12 passed job files to Docker through a temporary folder of the computer.

  1. Update BitPull to 0.1.12 or later: job files live in a Docker volume and no folder of the computer is shared.

Messages: file sharing, Docker wants to access

Fixed in BitPull 0.1.12

Windows installer: "Error opening file for writing"

Cause: BitPull's background service (bitpull-agent.exe) was still running and kept its file in use, e.g. after uninstalling.

  1. Press Cancel, then in PowerShell run: Get-Process bitpull-agent, bitpull-desktop -ErrorAction SilentlyContinue | Stop-Process -Force
  2. Run the installer again; if it still fails, restart Windows and run it first.
  3. From 0.1.11 the installer stops the background service by itself.

Messages: Error opening file for writing

Fixed in BitPull 0.1.11

Update failed: "None of the fallback platforms … were found in the response"

Cause: A new version was being published and the package for this system was not ready yet.

  1. Wait 15-20 minutes and press "Check for updates" again.
  2. Since 0.1.12 releases become visible only when every system is ready.

Messages: None of the fallback platforms, were found in the response

Fixed in BitPull 0.1.12

"Something went wrong: The agent does not respond"

Cause: After an update or a restart the background service took more than 40 seconds to start, usually while Docker was still starting.

  1. Wait a couple of minutes: the app retries every 30 seconds.
  2. Or quit BitPull from its tray/menu-bar icon and open it again.
  3. Update to 0.1.13 or later: the dashboard starts at once and slow checks continue in the background.
  4. The details are in ~/.bitpull/agent.log (Windows: %USERPROFILE%\.bitpull\agent.log).

Messages: The agent does not respond, agent.log

Fixed in BitPull 0.1.13

Downloading an image, speech or music model: "engine install failed: both 'recipe' and 'backend' are required"

Cause: The current Lemonade engine needs to be told which hardware to use (graphics card or processor); BitPull did not send it.

  1. Update the computer that lends the model to 0.1.14 or later and download the model again: BitPull now picks the best engine for that computer.

Messages: both 'recipe' and 'backend' are required, engine install failed

Fixed in BitPull 0.1.14

An open AI model returns an empty answer, or the answer takes minutes

Cause: Reasoning models (e.g. Qwen 3.5) could spend every token reasoning before answering; models running on a lender's processor are slow (a few tokens per second).

  1. The computer that lends the model should run BitPull 0.1.14 or later: models answer directly.
  2. Wait longer: bitpull set waitMinutes=20, or the "Wait up to" field in the app, or waitMinutes in the MCP tools.
  3. A job that is still running is not lost: check it later (job_status).

Messages: The model is still working, Model job running, empty answer

Fixed in BitPull 0.1.14 (answers), 0.1.15 (adjustable wait)

Lending stops when the computer goes to sleep

Cause: A sleeping computer is off the network. The screen turning off is fine; system sleep is not.

  1. Keep "Stay awake while lending" on (0.1.15 or later): the computer does not sleep while it runs a job.
  2. To lend all the time: Windows Settings > System > Power > Screen and sleep > When plugged in, put my device to sleep after: Never. macOS: System Settings > Battery > Options > Prevent automatic sleeping on power adapter when the display is off.

Messages: offline

Fixed in BitPull 0.1.15 keeps the computer awake during jobs

Login code "not found or expired"

Cause: Codes from bitpull login --device (or the bitpull_login tool) last 10 minutes and work once.

  1. Run bitpull login --device again and approve the new code on bitpull.cloud/device while logged in.

Messages: Code not found or expired, The code expired

macOS says the app is damaged or from an unidentified developer; Windows SmartScreen warns

Cause: BitPull builds are not notarized (macOS) or Authenticode-signed (Windows) yet; the downloads are verified by SHA-256 instead.

  1. Install with the script, which verifies the SHA-256 and avoids the macOS prompt: curl -fsSL https://bitpull.cloud/install.sh | sh
  2. macOS from the disk image: right-click the app > Open, or System Settings > Privacy & Security > Open Anyway.
  3. Windows: More info > Run anyway.

Messages: is damaged and can't be opened, unidentified developer, Windows protected your PC