Skip to content
The world does revolve around you.

Troubleshooting#

This page covers common failures by lifecycle stage: install, first run, and ongoing operation. Each entry has a symptom, a cause, and a fix. If your problem is not here, see Contact.

Check the diagnostic dashboard first

The Hub ships with a local diagnostic dashboard that checks your services and points at any obvious problem. Browse to:

http://localhost:8089/doctor

Look there before doing anything more invasive. It is read-only and safe.

Install#

Drag and drop does not accept the licence file#

Symptom

You drop ostler-licence.json onto the drop zone on the first screen of the installer, and nothing happens. The drop zone does not highlight, the file bounces back, or the installer ignores the drop.

Cause

One of three things:

  1. The file is not actually .json – your browser saved it as .json.txt or .json.download.
  2. macOS Gatekeeper is quarantining the file because it came from a browser; the drop is being intercepted by a security prompt that you missed.
  3. The licence JSON file is corrupted or signed against a different production key (rare; only happens if your welcome email is months old and we have rotated the signing key in the meantime).

Fix

  1. Rename the file to end in .json exactly. Run file ~/Downloads/ostler-licence.json in Terminal to confirm it is detected as JSON.
  2. Open Finder, right-click the file, choose Open With > TextEdit to release the quarantine flag, then close TextEdit and retry the drop.
  3. If neither works, click Paste licence or Stripe session ID below the drop zone and paste the contents of the JSON file directly, or paste the cs_... Stripe Checkout session ID from your receipt email. The installer fetches the licence from the licence server using that session ID.
  4. If even the paste path fails, email [email protected] with the order date and the address on the receipt and we will re-issue.

"Raw licence ID" friendly error after paste#

Symptom

You pasted something into the Paste licence or Stripe session ID field and the installer shows:

That looks like a raw licence ID rather than a Stripe session ID or the signed JSON. Open your welcome email and either drag the attached ostler-licence.json onto the drop zone, or copy the long cs_... value from the receipt.

Cause

A raw licence ID (the short opaque identifier shown in some emails) is not enough to verify the install. The installer needs either the full signed JSON or a Stripe Checkout session reference (cs_...) to fetch the JSON over a verified channel.

Fix

Open your welcome email. The attachment ostler-licence.json is the easiest path – drag it onto the drop zone. If you cannot find the email, click Download licence again on ostler.ai/welcome to re-download the JSON, or copy the cs_... session ID from your Stripe receipt and paste that.

Single admin dialog never appears#

Symptom

After licence verification, the macOS admin authorisation dialog (the standard system prompt asking for your password to authorise OstlerInstaller) does not appear. The installer hangs on a "Authorising..." screen.

Cause

The first-launch authorisation request can be blocked by:

  1. A managed-Mac (MDM) profile that disables admin prompts for non-admin users.
  2. The installer running with a child process that has lost its authorisation reference (rare; happens after macOS sleep mid-install).
  3. The user account does not have admin rights on this Mac.

Fix

  1. Confirm you are signed in as an admin user. System Settings > Users & Groups – your account must show Administrator.
  2. Quit the installer (Cmd-Q), restart it from /Applications/OstlerInstaller.app, and watch for the dialog – it sometimes fires in a separate Space if you have multiple desktops.
  3. If you have an MDM profile, ask your MDM administrator to allow admin authorisation for OstlerInstaller (signed by Developer ID Application: Creative Machines).

Email-support banner appears#

Symptom

The installer hits an error during Phase 3 and shows a red banner with two buttons: Email support and Copy log (raw).

Cause

Something in the install pipeline failed. The banner is the deliberate, designed failure surface – it is not a crash.

Fix

  1. Tap Email support. This opens your default mail client with a pre-filled mailto:[email protected] message containing a PII-redacted summary of the install log (versions, step names, error codes, and Hub identifiers; no personal data).
  2. Send it. We reply within 2 working days.
  3. If you want to send the raw, un-redacted log because you suspect we need machine-specific identifiers, tap Copy log (raw), confirm the warning modal that explains what the raw log contains, and paste the result into your email as you see fit.

You are not required to use the raw log; the PII-redacted version is enough to debug the great majority of install failures.

macOS Gatekeeper warns about an unsigned app#

Symptom

When you double-click OstlerInstaller.app, macOS shows a dialog saying the application cannot be opened because the developer cannot be verified, or asks you to confirm you want to open something from the internet.

Cause

The "developer cannot be verified" wording is shown for apps with no notarisation ticket. OstlerInstaller.app is signed and notarised; you should never see the unverifiable variant of the dialog for a clean download. The "downloaded from the internet" variant is normal and expected.

Fix

  1. Confirm the signing identity. In Terminal:
spctl -a -vv /Applications/OstlerInstaller.app

The output should include accepted and source=Notarized Developer ID and reference the certificate Developer ID Application: Creative Machines. If it does not, the download is corrupted – re-download from your welcome email.

  1. If the dialog says the file is "from the internet" (the friendly variant), click Open. macOS only asks this once per download.

  2. If the dialog says the developer cannot be verified at all, do not override the warning. Re-download the installer from the link in your welcome email; the original is probably corrupt or has been tampered with in transit.

Q1 macOS permission dialogs do not appear#

Symptom

You reach Question 1 of the guided setup but the four TCC dialogs (Contacts, Desktop, Downloads, Documents) do not fire. The Q1 screen just sits there waiting.

Cause

One of:

  1. You have previously denied these permissions to OstlerInstaller.app and macOS now silently refuses to ask again. The TCC subsystem keeps a per-bundle decision record.
  2. The NS*UsageDescription strings in the installer bundle were not loaded by macOS (rare; usually a sign the installer bundle has been moved or modified).
  3. You are running an older macOS that does not yet have the Documents folder TCC class (macOS 13 has it; very old macOS 12 betas did not).

Fix

  1. Open System Settings > Privacy & Security. Scroll through Contacts, Files & Folders > Documents, Files & Folders > Downloads, and Files & Folders > Desktop. Find OstlerInstaller (or Ostler) and toggle it on. If it is not listed, the dialog has not fired yet; continue to the next step.
  2. Quit the installer fully (Cmd-Q), wait five seconds, reopen it from /Applications/OstlerInstaller.app. The dialogs should now fire.
  3. If they still do not fire, tap Skip permissions on the Q1 screen. The installer continues; you will lose the auto-discovery of platform exports in ~/Downloads / ~/Desktop / ~/Documents but you can run ostler-import <path> after install instead.

Installer says "macOS only"#

Symptom

[fail] This installer is for macOS only.

Cause

You are running on Linux or Windows. The current Hub release is macOS only.

Fix

Run the installer on a Mac with Apple Silicon (M1 or later). Linux and Windows are not supported today.

Installer fails the RAM check#

Symptom

[fail] At least 16 GB RAM required. You have 8 GB. 24 GB recommended.

Cause

Local AI models need RAM. 8 GB Macs cannot run a model large enough to be useful.

Fix

Use a Mac with at least 16 GB of unified memory. The 16 GB tier runs the compact assistant – reliable, accurate, sub-second on short questions – with a smaller answer range than 24 GB. 24 GB is recommended for the standard 9-billion-parameter assistant.

Installer fails on disk space#

Symptom

[fail] Not enough disk space (12 GB). Free up space and try again.

Cause

The full install needs roughly 35 GB: container images, the AI model, the embedding model, the import pipeline, and headroom for your data.

Fix

Free up at least 35 GB on your boot volume. If the warning is between 15 GB and 35 GB the installer will continue, but expect the AI model download to fail.

Xcode Command Line Tools dialog never appears#

Symptom

The installer says it is installing Xcode Command Line Tools and waits, but no Apple dialog appears.

Cause

A previous failed install may have left the command-line tool selection in a bad state, or the dialog was dismissed.

Fix

In Terminal:

xcode-select --install

Accept the dialog, wait for the install to finish, then re-run the Hub installer.

Docker is installed but not running#

Symptom

[warn] Docker installed but not running. Will need to start it.

The installer pauses or eventually times out waiting for Docker.

Cause

The installer needs a working Docker daemon for the local databases. If you have Docker Desktop installed it must be running; if not, the installer will offer to install Colima (a lightweight headless alternative) instead.

Fix

Either:

  • Open Docker Desktop, wait until the whale icon stops animating, then re-run the installer.
  • Or quit Docker Desktop entirely and let the installer set up Colima for you. Colima is free, headless, and does not require a Docker subscription.

Colima fails to start#

Symptom

[warn] Colima failed to start. Trying Docker Desktop as fallback...

Cause

A stale Colima profile, an old QEMU process, or a partial install can prevent Colima from coming up cleanly.

Fix

colima stop
colima delete
colima start --cpu 2 --memory 4 --disk 30

If that still fails, install Docker Desktop, start it, then re-run the Hub installer.

docker-compose: command not found#

Symptom

The installer or ostler commands fail mentioning a missing docker-compose plugin.

Cause

Recent Docker installs ship compose as a CLI plugin (docker compose, two words) rather than the older docker-compose binary. Some shells cannot discover the plugin if ~/.docker/cli-plugins is not on the path.

Fix

mkdir -p ~/.docker/cli-plugins
ln -sf /opt/homebrew/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose
docker compose version

The last command should print a version. Re-run the failed installer step.

Ollama install times out#

Symptom

The installer reports that Ollama is not responding after a long wait.

Cause

The Ollama background service did not start, or another process is holding the same port.

Fix

curl http://localhost:11434/api/tags

If that errors:

  1. Open the Ollama menu-bar app to start the service.
  2. If Ollama is not installed at all, install it from ollama.com and re-run the Hub installer.
  3. Do not run ollama serve manually – it conflicts with the background service.

Port already in use#

Symptom

Error response from daemon: Ports are not available: ... bind: address already in use

Cause

Something else on your Mac is already listening on a port the Hub wants. Common offenders are old development databases or another local AI tool.

Fix

Find what is using the port and stop it:

# Replace 6333 with whichever port the error mentions.
lsof -nP -iTCP:6333 -sTCP:LISTEN

The output shows the process. If it is yours, stop it. If you cannot stop it and need the Hub on different ports, edit the corresponding *_URL env var in ~/.ostler/config/.env (for example QDRANT_URL, OXIGRAPH_URL, REDIS_URL) to point at the new port, then update the matching port in ~/.ostler/docker-compose.yml. See Reference: Environment variables.

Full Disk Access permission denied#

Symptom

The installer pauses asking you to grant Full Disk Access. After you grant it the installer still says the permission is missing.

Cause

macOS attaches Full Disk Access to a specific application binary. If you grant it to one Terminal binary and run the installer from a different one (for example, iTerm2 vs. Terminal.app, or a shell launched from VS Code), the grant does not transfer.

Fix

  1. Open System Settings > Privacy & Security > Full Disk Access.
  2. Make sure the application you are using to run the installer is in the list and toggled on. Add it if missing.
  3. Quit the application completely (Cmd-Q, not just close the window) and reopen it.
  4. Re-run the installer.

Contacts permission denied#

Symptom

The installer skips contacts import with a permission warning.

Cause

macOS gates the Contacts database with a separate consent prompt that you may have dismissed.

Fix

  1. Open System Settings > Privacy & Security > Contacts.
  2. Toggle on the application you are running the installer from.
  3. Quit and reopen it, then re-run the macOS extractors:
ostler-fda

Installer hangs at "downloading model"#

Symptom

The installer sits at the AI model download step for a long time.

Cause

The AI model is several gigabytes. On a slow connection it takes a while; if your network drops mid-download Ollama will retry.

Fix

Leave it for at least 20 minutes on a typical home connection. If it has clearly stalled (no network activity for several minutes), cancel with Ctrl-C and re-run the installer – Ollama resumes partial downloads.

First run#

Hub starts but the diagnostic dashboard reports failed services#

Symptom

The dashboard at http://localhost:8089/doctor shows one or more services as unhealthy, e.g.:

[ok]   ostler-api ........ healthy
[fail] ostler-store ....... not responding

Cause

A container failed to start, usually because Docker was paused mid-install or a port was in use.

Fix

Cycle the affected LaunchAgent (replace <label> with the failing service, e.g. com.ostler.api):

launchctl bootout gui/$UID/<label>
launchctl bootstrap gui/$UID/ ~/Library/LaunchAgents/<label>.plist

Then refresh the diagnostic dashboard at http://localhost:8089/doctor.

If the same service fails again, check its log file:

tail -f ~/.ostler/logs/<service-name>.log

Passphrase rejected on first unlock#

Symptom

You enter the passphrase you set during install and the Hub says it is wrong.

Cause

Likely typed wrong (passphrases are case-sensitive and may include trailing spaces). On rare occasions a keyboard layout mismatch (for example, a UK keyboard set to US layout) can swap symbols.

Fix

  • Try again carefully. The Hub does not lock you out, but does rate-limit repeated wrong attempts.
  • Switch keyboard layout to match what you used at install time.
  • If you genuinely cannot remember the passphrase, see Encryption passphrase forgotten below.

iOS app cannot find the Hub#

Symptom

The Ostler iOS app shows "Looking for Hub..." indefinitely or pairing times out.

Cause

One of:

  1. iPhone and Mac are not on the same Wi-Fi network.
  2. mDNS / Bonjour discovery is blocked (some corporate networks, some VPN configurations).
  3. The Hub's local listener is not running.

Fix

  1. Confirm both devices are on the same Wi-Fi network. A guest network and main network on the same router are usually isolated from each other.
  2. Disable VPN on the iPhone temporarily and retry.
  3. On the Mac, browse to http://localhost:8089/doctor and confirm the API service is healthy.
  4. If QR scanning fails, fall back to Pair with code in the Doctor dashboard's Pairing panel. The iOS app's QR scanner has a manual-entry field underneath where you can type the six-digit code. The QR carries the Hub address; you do not need to type the IP.

iOS app pairing code expired#

Symptom

The iOS app says the pairing code has expired or is invalid.

Cause

Pair codes are short-lived by design. If you start the pair flow and walk away, the code rotates.

Fix

On the Hub, open the diagnostic dashboard at http://localhost:8089/doctor and use the Pairing panel to generate a fresh code, then use it within a couple of minutes.

Ongoing operation#

Hub fails to start after macOS update#

Symptom

After a macOS upgrade, the Hub will not launch or services fail to bind.

Cause

macOS upgrades commonly reset Full Disk Access grants for terminals, and may invalidate Docker containers.

Fix

  1. Re-grant Full Disk Access to the application you use to run ostler-* commands.
  2. Restart the services. Cycle each affected LaunchAgent:
launchctl bootout gui/$UID/<label>
launchctl bootstrap gui/$UID/ ~/Library/LaunchAgents/<label>.plist

Then check http://localhost:8089/doctor.

  1. If the index appears empty or corrupted after the update, re-run OstlerInstaller from /Applications. The installer is re-run-safe: it detects the existing install and rebuilds the index from your local data without re-importing.

Encryption passphrase forgotten#

Symptom

You cannot remember the passphrase you set at install.

Cause

The passphrase is the only key to your encrypted databases. By design, we do not have a copy.

Fix

If you saved the recovery key the installer printed (a multi-word phrase, separate from your passphrase), the recovery flow is documented under Reference: CLI – use the recovery key to unlock and reset the passphrase.

The recovery key is shown once at install time and the installer offers to save it to your macOS Keychain. The current install posture is recorded at ~/.ostler/security-posture/install.json; check that file if you are unsure whether encryption is enabled.

If you did not save the recovery key, your databases are unrecoverable. The honest path forward is:

  1. Run ostler-uninstall, keeping your ~/Downloads exports in place.
  2. Re-run the installer with a new passphrase.
  3. Re-import your data from the GDPR exports.

This is the trade-off we make for not having access to your data ourselves. See the Encryption page for the full design and the FAQ for context.

Disk space pressure#

Symptom

macOS warns that your startup disk is almost full, or the Hub starts logging write failures.

Cause

Common culprits:

  • Old Docker images that are no longer referenced.
  • A large incoming GDPR export that has not been moved off ~/Downloads.
  • The wiki rebuild kept several historical snapshots.

Fix

# Show what is taking space inside Ostler's data directory.
du -sh ~/.ostler/* | sort -h

# Remove dangling Docker images (safe – only removes layers nothing references).
docker image prune

# A deeper clean – will list what it would delete and ask for confirmation.
docker system prune

For more aggressive cleanup, inspect what is in ~/.ostler/ with the du command above and remove items you no longer need (such as old log files under ~/.ostler/logs/). To start over completely, run ostler-uninstall and re-run the installer.

External drive (LaCie or similar) refuses to mount#

Symptom

You moved the Hub data directory to an external drive and after reboot the drive does not auto-mount, leaving the Hub unable to start.

Cause

External drives mount asynchronously after login. The Hub services start before the drive is ready.

Fix

  1. Wait for the drive to mount, then cycle the Hub LaunchAgents (replace <label> with each affected service such as com.ostler.api):

launchctl bootout gui/$UID/<label>
launchctl bootstrap gui/$UID/ ~/Library/LaunchAgents/<label>.plist
2. To make this automatic, ship the Hub's launch agent with a dependency on the mount path. See Reference: Configuration under "External storage". 3. If the drive does not mount at all: open Disk Utility, select the drive, click First Aid. If the drive uses an unsupported filesystem (NTFS in particular), the Hub will not be able to write to it – move data back to an APFS volume.

Browser extension stops capturing#

Symptom

The Safari or Chrome extension shows a red dot or "disconnected" state.

Cause

The extension talks to the Hub over your local network. If the Hub is asleep or stopped, the extension cannot reach it.

Fix

  1. On the Mac, check running services with launchctl list | grep com.ostler and the diagnostic dashboard at http://localhost:8089/doctor.
  2. If you are on a different Mac to the Hub, confirm both are on the same network.
  3. Reopen the extension's options page and re-enter the Hub URL if it has changed.

Your assistant replies slowly or not at all#

Symptom

Messages to your assistant in iMessage or WhatsApp take minutes to arrive, or never arrive.

Cause

The local AI model is large and your Mac may be paging memory, especially on 16 GB machines. Or the messaging bridge has lost its connection.

Fix

Check the running services and inspect the assistant log:

launchctl list | grep com.ostler
tail -f ~/.ostler/logs/assistant.log

Common fixes:

  • Quit memory-hungry apps (browsers with many tabs, video editors).
  • Drop to a smaller AI model. Pull it with ollama pull <model-name> and set the override via the relevant OLLAMA_* keys in ~/.ostler/config/.env – see Reference: Environment variables.
  • Restart the messaging bridge by cycling its LaunchAgent (replace <label> with the bridge label, e.g. com.ostler.assistant):
launchctl bootout gui/$UID/<label>
launchctl bootstrap gui/$UID/ ~/Library/LaunchAgents/<label>.plist

The assistant replied as me or wrong identity in a group chat#

Symptom

In a group chat, the assistant attributes statements to the wrong person, or appears to speak as you.

Cause

Group-chat identity resolution is harder than 1:1 messaging. The current build conservatively limits where the assistant participates.

Fix

By default the assistant only replies to messages from numbers and contacts on an explicit allow-list, configured inside the messaging bridge. If you see it replying in a group it should not be in:

  1. Open the Doctor dashboard at http://localhost:8089/doctor and find the Messaging channels panel.
  2. Remove the offending number / contact from the allow-list there, or pause the channel entirely.
  3. Restart the messaging bridge by cycling its LaunchAgent (see the launchctl cycle above).

Where to go next#

  • FAQ for non-technical questions.
  • Contact to reach a human if none of the above helps.
  • Architecture for the design behind the diagnostics.