Troubleshooting and FAQ

The messages rAPIdtools prints when something goes wrong, what causes each one, and how to fix it, followed by answers to common questions about keys, retries, logging and the GUI.

Each entry shows the actual message, then the cause and the fix. Installation problems are covered in Installation; GUI and server set-up in Graphical Interface and Deployment.

Installation and environment

operator torchvision::nms does not exist Cause: torch and torchvision were installed from different package indexes, so the torchvision wheel was built against a different torch; every model module then fails on import. Fix: install both from the same index in one command, for example pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu for a CPU-only machine, then reinstall rapidtools.

<model id> requires transformers>=<version>. Run pip install "transformers>=". Cause: a local model (Gemma 4 and other recent checkpoints) needs a newer transformers than the one in the environment. The package itself requires transformers>=5.15. Fix: run the pip install command in the message.

GPU OUT OF MEMORY ERROR. Try smaller images, smaller batch sizes, or set load_in_4bit=True. Cause: the local model or SAM 3 did not fit on the card for that batch. The batch is reported as failed and the run continues. Fix: lower batch_size, use smaller crops, or load the model with load_in_4bit=True. On a shared workstation close other GPU work first.

API keys and authentication

<Provider> key is missing. Provide it as an argument or set the <VARIABLE> environment variable. Cause: no key was passed to the model wrapper and the environment variable for that provider is unset. Fix: pass api_key=... (a string, or a path to a text file holding the key) or set the variable. The wrappers consult these variables, in order:

Provider	Environment variables
Gemini	GOOGLE_API_KEY, GEMINI_API_KEY
Anthropic (Claude)	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
Meta Model API (Muse Spark)	MODEL_API_KEY, META_API_KEY
Qwen (Model Studio)	DASHSCOPE_API_KEY, QWEN_API_KEY

API key file not found at: <path> Cause: a pathlib.Path was given as the key but no file exists there. Fix: check the path, or pass the key itself as a string.

Hugging Face login failed: ... or Failed to auto-authenticate with Hugging Face: ... Cause: a local model needs gated weights (Gemma, Llama, ...) and no Hugging Face token could be obtained. rapidtools.auth.login() tries an explicit token, then a token cached by huggingface-cli login, then the token file in the rapidtools dataset registry; the failure is logged, not raised, and the download then fails. Fix: run huggingface-cli login, or call rapidtools.auth.login(token='hf_...') once; accept the model's license on its Hugging Face page.

Mapillary access token is required. Cause: a Mapillary client or street-level component was created without a token. Fix: pass access_token='MLY|...'. In the GUI, RAPID token fetches the one used by the examples. See Street-Level Imagery Workflows.

Running inference

Request failed for asset <id> (consecutive failures: N); pausing all workers for Ns. The asset will be retried later. Cause: a hosted API returned a rate limit, timeout or other transient error. RateLimitPolicy pauses every worker for cooldown_seconds (default 30) multiplied by the number of consecutive failures; the first success resets the multiplier. Failed assets are retried in up to max_asset_retries (default 2) extra passes. Fix: usually nothing; the pass completes. For a strict quota, lower max_workers or raise cooldown_seconds.

Asset <id> was rejected by the provider (<error>); it will not be retried. Cause: the provider refused the request outright (a safety block or a 4xx response). These are returned with retryable=False, so they neither pause the other workers nor join the retry passes. Fix: inspect the asset's image and the prompt; the error text comes from the provider.

N assets still failed after all retries: ... / N assets were rejected by the provider and not retried. Cause: the end-of-run summary of the two cases above. Fix: check the provider's quota and the rejected assets' crops, then re-run the analyzer on the affected assets. Assets without downloaded images are skipped up front (N assets have no downloaded images and are skipped.), so run the imagery extractor first.

Image file does not exist at: <path> Cause: an ImageAsset points at a file that was moved or deleted after extraction, or a GeoJSON written on another machine was loaded here. Fix: restore the files under the original save_directory, or run the imagery extractor again before analysis. See Data Formats and Export.

OperationCancelled Cause: not an error. A cancel_event was set (or Cancel was pressed in the GUI) and the component stopped at the next asset, tile or batch. It derives from RuntimeError. Fix: nothing; everything produced so far is kept on the assets. Catch it with except OperationCancelled: in scripts.

The GUI and shared servers

Could not start the rapidtools GUI on <host>:<port> (...). Is another instance already running? Pick another port with --port. Cause: the port is taken, usually by an earlier rapidtools-gui. Fix: stop the other instance or start with --port 8766.

The GUI is reachable from other machines without an access token. Add --token auto (or --token <secret>) before sharing it. Cause: the server was bound to a non-loopback interface (--host 0.0.0.0) with no token. Fix: add --token auto or set RAPIDTOOLS_GUI_TOKEN.

Sign in required. (HTTP 401) or That token was not accepted. on the sign-in page Cause: the server runs with a token and the browser did not present it, or the token was rotated. Fix: open the share link http://<host>:8765/?token=... printed at start-up (Share this link with colleagues: ...), or type the token on the sign-in page.

A job is already running (<name>). (HTTP 409) Cause: everyone connected shares one job queue, and one detection or inference runs at a time. Fix: wait or press Cancel; for a team working in parallel, run a second server on another port with its own token.

Access is limited to <directory>. (HTTP 403) Cause: the server was started with --data-root and the path lies outside it. Fix: copy the file under the data root (DATA_DIR in the Docker setup) and pick it from the file browser.

Email is not set up on this server: start it with --smtp-host (or set RAPIDTOOLS_SMTP_HOST). A webhook URL works without any setup. Cause: a notification email address was entered but the server has no SMTP relay configured. Fix: give a webhook URL instead, or start the server with the --smtp-* flags (the password comes from RAPIDTOOLS_SMTP_PASSWORD).

Enter an email address or a webhook URL (https://...). Cause: the notification target is neither an email address nor an https:// URL. Fix: correct the target.

Frequently asked questions

Why do I see no progress messages in my script or notebook? Importing rAPIdtools never touches logging configuration. Call rapidtools.configure_logging() once ('DEBUG' for more detail). The rapidtools logger then stops propagating to the root logger, so messages print once even when your application configured root logging. The rapidtools-gui console script calls it for you.

How are network failures retried? Network components share rapidtools.config.get_configured_session(), a requests.Session with 5 retries, a backoff factor of 1, a 30-second timeout and retries on 429, 500, 502, 503 and 504 for HEAD, GET and OPTIONS. Provider API clients use rapidtools.models.api_base.api_session(), which re-sends POST requests only after 429, 503 or 529, statuses that guarantee the provider did not process, and therefore did not bill, the request. Other failures are reported to the caller instead of being repeated.

Where does the GUI write its files? Downloads, crops and GeoJSON outputs go under --output-dir (default ./asset_analysis_output). The RAPID route database is cached as survey_routes_z13.json.gz under ~/.cache/rapidtools; the first start builds it in two to three minutes on a server, about 15 seconds on a fast workstation.

The GUI opens on the first start but the map has no survey routes yet. The route database is being built; GET /api/street/routes reports its status and refresh in the layer panel rebuilds it.

Browser alerts do not appear on a shared server. Desktop notifications need HTTPS. Over plain HTTP on an intranet use email or webhook notifications; the Docker and Caddy setup in Deployment serves HTTPS.

Is the token enough to expose the server on the internet? No. The token protects the app, not the transport, which is plain HTTP. Keep the server on your institution's network or a VPN, or put it behind the Caddy TLS setup in deploy/. The token is the only protection and everyone shares it; rotate it when someone leaves.

Why does my test or notebook try to download model weights? Local model wrappers call ensure_huggingface_login() and load the checkpoint on first use. The repository's own tests avoid this by patching rapidtools.auth.get_token and rapidtools.models.local_base.ensure_huggingface_login in tests/conftest.py and by substituting fake processors and models; do the same in your tests. See Contributing and Development.

A model, prompt or component I need is not covered here. Supported Models lists every backend and its options; Vision-Language Models covers prompting; the changelog's Unreleased section lists behaviour that changed since the last release, such as the retry policy and ModelOutput.failure(). For anything else, get in touch as described in the next section, with the message, the command and the rapidtools version.

Still stuck? Get in touch

Short notes are as welcome as long ones. There are two ways to reach us, depending on whether you use GitHub; the feedback page of the documentation has the same routes.

Without a GitHub account

Email is all you need: uwrapid@uwrapid.org. Send the error message, the command or script, the rapidtools version (python -c "import rapidtools; print(rapidtools.__version__)"), your operating system, and what you expected to happen; a screenshot of the GUI helps. A maintainer will answer and, with your agreement, turn the message into a GitHub issue so others with the same problem can find the fix. Leave API keys and access tokens out of the message.

With a GitHub account

The three forms below open an issue on the project's GitHub page, where other users can see it, add to it and follow the fix. They need a GitHub account: clicking a link asks you to sign in first, and GitHub offers to create a free account on that page. If you would rather not, use the email route above.

I want to...	Open
Report something that fails or gives a wrong result	Bug report
Ask for a capability that is missing	Feature request
Ask a question, or say what worked and what did not	Feedback or question

Suspected security problems are handled privately, never in a public issue: open a security advisory with a GitHub account, or email the address above with "security" in the subject.